Initial commit

Author: sunsided

.gitignore

@@ -0,0 +1,2 @@
+/target
+/Cargo.lock

CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+This project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2023-07-10
+
+### Internal
+
+- 🎉 Initial release.
+
+[0.1.0]: https://github.com/sunsided/swap3-rs/releases/tag/0.1.0

Cargo.toml

@@ -0,0 +1,26 @@
+[package]
+name = "swap3"
+version = "0.1.0"
+description = "Swapping of three references, rotating the values left or right"
+authors = ["Markus Mayer"]
+repository = "https://github.com/sunsided/swap3-rs"
+keywords = ["swapping", "rotation"]
+categories = ["algorithms"]
+license = "MIT"
+readme = "README.md"
+edition = "2021"
+
+[features]
+unsafe = []
+
+[dev-dependencies]
+criterion = "0.5.1"
+rand = "0.8.5"
+
+[[bench]]
+name = "rot_slice"
+harness = false
+
+[package.metadata.docs.rs]
+all-features = true
+rustdoc-args = ["--cfg", "docsrs"]

LICENSE.md

@@ -0,0 +1,25 @@
+# The MIT License (MIT)
+
+Copyright © 2023 Markus Mayer
+Copyright © The Rust Core Library authors
+
+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.

README.md

@@ -0,0 +1,34 @@
+# swap3
+
+Provides utility functions for simultaneously swapping three values by rotating them
+either left (`abc` → `bca`) or right (`abc` → `cab`). These functions can come in handy e.g.
+when rotating elements of a binary tree in list representation.
+
+The provided functions work on arbitrary types and do *not* require the type to be `Clone`, `Copy`
+or `Default`.
+
+## Examples
+
+For individual references, the `swap3_bca` (rotate left) and `swap3_cab` (rotate right)
+functions are available:
+
+```rust
+fn swap3_bca() {
+    let mut a = 10;
+    let mut b = 20;
+    let mut c = 30;
+
+    swap3::swap3_bca(&mut a, &mut b, &mut c);
+    assert_eq!([a, b, c], [20, 30, 10]);
+}
+```
+
+For slices, the `swap3_bca_slice` and `swap3_cab_slice` functions can be used:
+
+```rust
+fn swap3_bca() {
+    let mut vec = vec![10, 20, 30, 40, 50, 60];
+    swap3::swap3_bca_slice(&mut vec, 0, 1, 4);
+    assert_eq!(vec, &[30, 50, 30, 40, 10, 60]);
+}
+```

benches/rot_slice.rs

@@ -0,0 +1,70 @@
+use criterion::{black_box, criterion_group, criterion_main, Criterion};
+use rand::prelude::*;
+use swap3::slice;
+
+pub fn criterion_benchmark(c: &mut Criterion) {
+    let indexes = get_indexes(42);
+
+    c.bench_function("bca_safe", |bencher| {
+        let mut values = black_box(get_values());
+        bencher.iter(|| {
+            for (a, b, c) in indexes.iter().cloned() {
+                slice::bca_safe(&mut values, a, b, c)
+            }
+        })
+    });
+
+    #[cfg(feature = "unsafe")]
+    c.bench_function("bca_unsafe", |bencher| {
+        let mut values = black_box(get_values());
+        bencher.iter(|| {
+            for (a, b, c) in indexes.iter().cloned() {
+                slice::bca_unsafe(&mut values, a, b, c)
+            }
+        })
+    });
+
+    c.bench_function("cab_safe", |bencher| {
+        let mut values = black_box(get_values());
+        bencher.iter(|| {
+            for (a, b, c) in indexes.iter().cloned() {
+                slice::cab_safe(&mut values, a, b, c)
+            }
+        })
+    });
+
+    #[cfg(feature = "unsafe")]
+    c.bench_function("cab_unsafe", |bencher| {
+        let mut values = black_box(get_values());
+        bencher.iter(|| {
+            for (a, b, c) in indexes.iter().cloned() {
+                slice::cab_unsafe(&mut values, a, b, c)
+            }
+        })
+    });
+}
+
+fn get_values() -> Vec<u64> {
+    (0..100).map(|v| v + 1000).collect()
+}
+
+fn get_indexes(seed: u64) -> Vec<(usize, usize, usize)> {
+    let mut rng = StdRng::seed_from_u64(seed);
+    (0..100)
+        .map(|_| {
+            let a = rng.gen_range(0..100);
+            let mut b = rng.gen_range(0..100);
+            while b == a {
+                b = rng.gen_range(0..100);
+            }
+            let mut c = rng.gen_range(0..100);
+            while c == a || c == b {
+                c = rng.gen_range(0..100);
+            }
+            (a, b, c)
+        })
+        .collect()
+}
+
+criterion_group!(benches, criterion_benchmark);
+criterion_main!(benches);