strength_reduce-0.2.4/.cargo_vcs_info.json0000644000000001360000000000100142240ustar { "git": { "sha1": "5b0a43d9d672ee2ac4e471f201fb13417a0a0c71" }, "path_in_vcs": "" }strength_reduce-0.2.4/.gitignore000064400000000000000000000000410072674642500150270ustar 00000000000000/target **/*.rs.bk Cargo.lock strength_reduce-0.2.4/Cargo.toml0000644000000020760000000000100122270ustar # THIS FILE IS AUTOMATICALLY GENERATED BY CARGO # # When uploading crates to the registry Cargo will automatically # "normalize" Cargo.toml files for maximal compatibility # with all versions of Cargo and also rewrite `path` dependencies # to registry (e.g., crates.io) dependencies. # # If you are reading this file be aware that the original Cargo.toml # will likely look very different (and much more reasonable). # See Cargo.toml.orig for the original contents. [package] name = "strength_reduce" version = "0.2.4" authors = ["Elliott Mahler "] description = "Faster integer division and modulus operations" documentation = "http://docs.rs/strength_reduce" readme = "README.md" keywords = [ "arithmetic", "strength", "reduction", "division", "modulus", ] categories = [ "algorithms", "data-structures", ] license = "MIT OR Apache-2.0" repository = "http://github.com/ejmahler/strength_reduce" [dev-dependencies.num-bigint] version = "0.4" [dev-dependencies.proptest] version = "1.0.0" [dev-dependencies.rand] version = "0.8" strength_reduce-0.2.4/Cargo.toml.orig000064400000000000000000000010370072674642500157340ustar 00000000000000[package] name = "strength_reduce" version = "0.2.4" authors = ["Elliott Mahler "] description = "Faster integer division and modulus operations" license = "MIT OR Apache-2.0" repository = "http://github.com/ejmahler/strength_reduce" documentation = "http://docs.rs/strength_reduce" keywords = ["arithmetic", "strength", "reduction", "division", "modulus"] categories = ["algorithms", "data-structures"] readme = "README.md" [dev-dependencies] proptest = "1.0.0" num-bigint = "0.4" rand = "0.8" strength_reduce-0.2.4/LICENSE-APACHE000064400000000000000000000264500072674642500147770ustar 00000000000000 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. strength_reduce-0.2.4/LICENSE-MIT000064400000000000000000000020750072674642500145040ustar 00000000000000Copyright (c) 2015 The RustFFT 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. strength_reduce-0.2.4/README.md000064400000000000000000000054460072674642500143340ustar 00000000000000# strength_reduce [![crate](https://img.shields.io/crates/v/strength_reduce.svg)](https://crates.io/crates/strength_reduce) [![license](https://img.shields.io/crates/l/strength_reduce.svg)](https://crates.io/crates/strength_reduce) [![documentation](https://docs.rs/strength_reduce/badge.svg)](https://docs.rs/strength_reduce/) ![minimum rustc 1.26](https://img.shields.io/badge/rustc-1.26+-red.svg) `strength_reduce` implements integer division and modulo via "arithmetic strength reduction". Modern processors can do multiplication and shifts much faster than division, and "arithmetic strength reduction" is an algorithm to transform divisions into multiplications and shifts. Compilers already perform this optimization for divisors that are known at compile time; this library enables this optimization for divisors that are only known at runtime. Benchmarking shows a 5-10x speedup on integer division and modulo operations. This library is intended for hot loops like the example below, where a division is repeated many times in a loop with the divisor remaining unchanged. There is a setup cost associated with creating stength-reduced division instances, so using strength-reduced division for 1-2 divisions is not worth the setup cost. The break-even point differs by use-case, but is typically low: Benchmarking has shown that takes 3 to 4 repeated divisions with the same StengthReduced## instance to be worth it. `strength_reduce` is `#![no_std]` See the [API Documentation](https://docs.rs/strength_reduce/) for more details. ## Example ```rust use strength_reduce::StrengthReducedU64; let mut my_array: Vec = (0..500).collect(); let divisor = 3; let modulo = 14; // slow naive division and modulo for element in &mut my_array { *element = (*element / divisor) % modulo; } // fast strength-reduced division and modulo let reduced_divisor = StrengthReducedU64::new(divisor); let reduced_modulo = StrengthReducedU64::new(modulo); for element in &mut my_array { *element = (*element / reduced_divisor) % reduced_modulo; } ``` ## Testing `strength_reduce` uses `proptest` to generate test cases. In addition, the `u8` and `u16` problem spaces are small enough that we can exhaustively test every possible combination of numerator and divisor. However, the `u16` exhaustive test takes several minutes to run, so it is marked `#[ignore]`. Before submitting pull requests, please test with `cargo test -- --ignored` at least once. ## Compatibility The `strength_reduce` crate requires rustc 1.26 or greater. ## License Licensed under either of * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0) * MIT license ([LICENSE-MIT](LICENSE-MIT) or https://opensource.org/licenses/MIT) at your option. strength_reduce-0.2.4/RELEASES.md000064400000000000000000000023760072674642500146010ustar 00000000000000# Release 0.2.4 (2022-11-07) ### Fixes - Fixed broken MIT license file link - Added missing license files to repository - Upgraded dependencies to proptest 1.0.0, num-bigint 0.4, rand 0.8 - Typo fixes in docs # Release 0.2.3 (2019-12-27) ### Fixes - Fixed a compile error on rustc 1.26 - Added `StrengthReducedU128` # Release 0.2.2 (2019-06-12) ### Changes - Rewrote the strength reduction algorithm to require less code and less branching. - Significantly reduced the setup cost of StrengthReducedU64. It now breaks even at 3-4 divisions, instead of 30-40. # Release 0.2.1 (2019-01-04) ### Fixes - Fixed a class of bugs for certain divisors with very large numerators, where the returned quotient was off by one. # Release 0.2.0 (2019-01-03) ### Breaking Changes - `strength_reduce` is now marked `#[!no_std]` # Release 0.1.1 (2019-01-03) - Added the readme to cargo.tom, so that it can be rendered directly from crates.io # Release 0.1.0 (2019-01-03) - Initial release. Support for computing strength-reduced division and modulo for unsigned integers: - `u8`: `StrengthReducedU8` - `u16`: `StrengthReducedU16` - `u32`: `StrengthReducedU32` - `u64`: `StrengthReducedU64` - `usize`: `StrengthReducedUsize` strength_reduce-0.2.4/benches/strength_reduce_benchmarks.rs000064400000000000000000000176030072674642500224120ustar 00000000000000#![feature(test)] extern crate test; extern crate strength_reduce; extern crate rand; // rustc incorrectly says these are unused #[allow(unused_imports)] use rand::{rngs::StdRng, SeedableRng, distributions::Distribution, distributions::Uniform}; const REPETITIONS: usize = 1000; macro_rules! bench_unsigned { ($struct_name:ident, $primitive_type:ident) => ( #[inline(never)] fn compute_repeated_division_primitive(numerators: &[$primitive_type], divisor: $primitive_type) -> $primitive_type { let mut sum = 0; for numerator in numerators { sum += *numerator / divisor; } sum } #[inline(never)] fn compute_repeated_division(numerators: &[$primitive_type], divisor: strength_reduce::$struct_name) -> $primitive_type { let mut sum = 0; for numerator in numerators { sum += *numerator / divisor; } sum } #[inline(never)] fn compute_single_division(divisors: &[$primitive_type]) -> $primitive_type { let mut sum = 0; for divisor in divisors { let reduced_divisor = strength_reduce::$struct_name::new(*divisor); sum += 100 / reduced_divisor; } sum } #[inline(never)] fn compute_repeated_modulo_primitive(numerators: &[$primitive_type], divisor: $primitive_type) -> $primitive_type { let mut sum = 0; for numerator in numerators { sum += *numerator % divisor; } sum } #[inline(never)] fn compute_repeated_modulo(numerators: &[$primitive_type], divisor: strength_reduce::$struct_name) -> $primitive_type { let mut sum = 0; for numerator in numerators { sum += *numerator % divisor; } sum } #[inline(never)] fn compute_repeated_divrem(numerators: &[$primitive_type], divisor: strength_reduce::$struct_name) -> ($primitive_type, $primitive_type) { let mut div_sum = 0; let mut rem_sum = 0; for numerator in numerators { let (div_value, rem_value) = strength_reduce::$struct_name::div_rem(*numerator, divisor); div_sum += div_value; rem_sum += rem_value; } (div_sum, rem_sum) } fn gen_numerators() -> Vec<$primitive_type> { test::black_box((0..std::$primitive_type::MAX).rev().cycle().take(REPETITIONS).collect::>()) } #[bench] fn division_standard(b: &mut test::Bencher) { let numerators = gen_numerators(); let divisor = 6; b.iter(|| { test::black_box(compute_repeated_division_primitive(&numerators, divisor)); }); } #[bench] fn repeated_division_reduced_power2(b: &mut test::Bencher) { let reduced_divisor = strength_reduce::$struct_name::new(8); let numerators = gen_numerators(); b.iter(|| { test::black_box(compute_repeated_division(&numerators, reduced_divisor)); }); } #[bench] fn repeated_division_reduced(b: &mut test::Bencher) { let reduced_divisor = strength_reduce::$struct_name::new(6); let numerators = gen_numerators(); b.iter(|| { test::black_box(compute_repeated_division(&numerators, reduced_divisor)); }); } #[bench] fn modulo_standard(b: &mut test::Bencher) { let numerators = gen_numerators(); let divisor = 6; b.iter(|| { test::black_box(compute_repeated_modulo_primitive(&numerators, divisor)); }); } #[bench] fn repeated_modulo_reduced_power2(b: &mut test::Bencher) { let reduced_divisor = strength_reduce::$struct_name::new(8); let numerators = gen_numerators(); b.iter(|| { test::black_box(compute_repeated_modulo(&numerators, reduced_divisor)); }); } #[bench] fn repeated_modulo_reduced(b: &mut test::Bencher) { let reduced_divisor = strength_reduce::$struct_name::new(6); let numerators = gen_numerators(); b.iter(|| { test::black_box(compute_repeated_modulo(&numerators, reduced_divisor)); }); } #[bench] fn repeated_divrem_reduced_power2(b: &mut test::Bencher) { let reduced_divisor = strength_reduce::$struct_name::new(8); let numerators = gen_numerators(); b.iter(|| { test::black_box(compute_repeated_divrem(&numerators, reduced_divisor)); }); } #[bench] fn repeated_divrem_reduced(b: &mut test::Bencher) { let reduced_divisor = strength_reduce::$struct_name::new(6); let numerators = gen_numerators(); b.iter(|| { test::black_box(compute_repeated_divrem(&numerators, reduced_divisor)); }); } #[bench] fn single_division_reduced_power2(b: &mut test::Bencher) { let divisors = test::black_box(vec![8; REPETITIONS]); b.iter(|| { test::black_box(compute_single_division(&divisors)); }); } #[bench] fn single_division_reduced(b: &mut test::Bencher) { let divisors = test::black_box(vec![core::$primitive_type::MAX; REPETITIONS]); b.iter(|| { test::black_box(compute_single_division(&divisors)); }); } ) } mod bench_u08 { use super::*; bench_unsigned!(StrengthReducedU8, u8); } mod bench_u16 { use super::*; bench_unsigned!(StrengthReducedU16, u16); } mod bench_u32 { use super::*; bench_unsigned!(StrengthReducedU32, u32); } mod bench_u64 { use super::*; bench_unsigned!(StrengthReducedU64, u64); // generates random divisors with values in the range [1< Vec { assert!(bit_min < bit_max); assert!(bit_max <= 64); let min_value = 1u64 << bit_min; let max_value = 1u64.checked_shl(bit_max).map_or(core::u64::MAX, |v| v - 1); let mut gen = StdRng::seed_from_u64(5673573); let dist = Uniform::new_inclusive(min_value, max_value); (0..count).map(|_| dist.sample(&mut gen)).collect() } // since the constructor for StrengthReducedU64 is so dependent on input size, we're going to do a few more targeted "single division" tests at specific sizes, so we can measure each "size class" separately #[bench] fn targeted_single_division_32bit(b: &mut test::Bencher) { let divisors = test::black_box(generate_random_divisors(0, 32, REPETITIONS)); b.iter(|| { test::black_box(compute_single_division(&divisors)); }); } #[bench] fn targeted_single_division_64bit(b: &mut test::Bencher) { let divisors = test::black_box(generate_random_divisors(32, 64, REPETITIONS)); b.iter(|| { test::black_box(compute_single_division(&divisors)); }); } } mod bench_u128 { use super::*; bench_unsigned!(StrengthReducedU128, u128); // generates random divisors with values in the range [1< Vec { assert!(bit_min < bit_max); assert!(bit_max <= 128); let min_value = 1u128 << bit_min; let max_value = 1u128.checked_shl(bit_max).map_or(core::u128::MAX, |v| v - 1); let mut gen = StdRng::seed_from_u64(5673573); let dist = Uniform::new_inclusive(min_value, max_value); (0..count).map(|_| dist.sample(&mut gen)).collect() } // since the constructor for StrengthReducedU128 is so dependent on input size, we're going to do a few more targeted "single division" tests at specific sizes, so we can measure each "size class" separately #[bench] fn targeted_single_division_032bit(b: &mut test::Bencher) { let divisors = test::black_box(generate_random_divisors(0, 32, REPETITIONS)); b.iter(|| { test::black_box(compute_single_division(&divisors)); }); } #[bench] fn targeted_single_division_064bit(b: &mut test::Bencher) { let divisors = test::black_box(generate_random_divisors(32, 64, REPETITIONS)); b.iter(|| { test::black_box(compute_single_division(&divisors)); }); } #[bench] fn targeted_single_division_096bit(b: &mut test::Bencher) { let divisors = test::black_box(generate_random_divisors(64, 96, REPETITIONS)); b.iter(|| { test::black_box(compute_single_division(&divisors)); }); } #[bench] fn targeted_single_division_128bit(b: &mut test::Bencher) { let divisors = test::black_box(generate_random_divisors(96, 128, REPETITIONS)); b.iter(|| { test::black_box(compute_single_division(&divisors)); }); } }strength_reduce-0.2.4/src/lib.rs000064400000000000000000000477740072674642500147720ustar 00000000000000//! `strength_reduce` implements integer division and modulo via "arithmetic strength reduction" //! //! Modern processors can do multiplication and shifts much faster than division, and "arithmetic strength reduction" is an algorithm to transform divisions into multiplications and shifts. //! Compilers already perform this optimization for divisors that are known at compile time; this library enables this optimization for divisors that are only known at runtime. //! //! Benchmarking shows a 5-10x speedup or integer division and modulo operations. //! //! # Example: //! ``` //! use strength_reduce::StrengthReducedU64; //! //! let mut my_array: Vec = (0..500).collect(); //! let divisor = 3; //! let modulo = 14; //! //! // slow naive division and modulo //! for element in &mut my_array { //! *element = (*element / divisor) % modulo; //! } //! //! // fast strength-reduced division and modulo //! let reduced_divisor = StrengthReducedU64::new(divisor); //! let reduced_modulo = StrengthReducedU64::new(modulo); //! for element in &mut my_array { //! *element = (*element / reduced_divisor) % reduced_modulo; //! } //! ``` //! //! This library is intended for hot loops like the example above, where a division is repeated many times in a loop with the divisor remaining unchanged. //! There is a setup cost associated with creating stength-reduced division instances, so using strength-reduced division for 1-2 divisions is not worth the setup cost. //! The break-even point differs by use-case, but is typically low: Benchmarking has shown that takes 3 to 4 repeated divisions with the same StengthReduced## instance to be worth it. //! //! `strength_reduce` is `#![no_std]` //! //! The optimizations that this library provides are inherently dependent on architecture, compiler, and platform, //! so test before you use. #![no_std] #[cfg(test)] extern crate num_bigint; #[cfg(test)] extern crate rand; use core::ops::{Div, Rem}; mod long_division; mod long_multiplication; /// Implements unsigned division and modulo via mutiplication and shifts. /// /// Creating a an instance of this struct is more expensive than a single division, but if the division is repeated, /// this version will be several times faster than naive division. #[derive(Clone, Copy, Debug)] pub struct StrengthReducedU8 { multiplier: u16, divisor: u8, } impl StrengthReducedU8 { /// Creates a new divisor instance. /// /// If possible, avoid calling new() from an inner loop: The intended usage is to create an instance of this struct outside the loop, and use it for divison and remainders inside the loop. /// /// # Panics: /// /// Panics if `divisor` is 0 #[inline] pub fn new(divisor: u8) -> Self { assert!(divisor > 0); if divisor.is_power_of_two() { Self{ multiplier: 0, divisor } } else { let divided = core::u16::MAX / (divisor as u16); Self{ multiplier: divided + 1, divisor } } } /// Simultaneous truncated integer division and modulus. /// Returns `(quotient, remainder)`. #[inline] pub fn div_rem(numerator: u8, denom: Self) -> (u8, u8) { let quotient = numerator / denom; let remainder = numerator % denom; (quotient, remainder) } /// Retrieve the value used to create this struct #[inline] pub fn get(&self) -> u8 { self.divisor } } impl Div for u8 { type Output = u8; #[inline] fn div(self, rhs: StrengthReducedU8) -> Self::Output { if rhs.multiplier == 0 { (self as u16 >> rhs.divisor.trailing_zeros()) as u8 } else { let numerator = self as u16; let multiplied_hi = numerator * (rhs.multiplier >> 8); let multiplied_lo = (numerator * rhs.multiplier as u8 as u16) >> 8; ((multiplied_hi + multiplied_lo) >> 8) as u8 } } } impl Rem for u8 { type Output = u8; #[inline] fn rem(self, rhs: StrengthReducedU8) -> Self::Output { if rhs.multiplier == 0 { self & (rhs.divisor - 1) } else { let product = rhs.multiplier.wrapping_mul(self as u16) as u32; let divisor = rhs.divisor as u32; let shifted = (product * divisor) >> 16; shifted as u8 } } } // small types prefer to do work in the intermediate type macro_rules! strength_reduced_u16 { ($struct_name:ident, $primitive_type:ident) => ( /// Implements unsigned division and modulo via mutiplication and shifts. /// /// Creating a an instance of this struct is more expensive than a single division, but if the division is repeated, /// this version will be several times faster than naive division. #[derive(Clone, Copy, Debug)] pub struct $struct_name { multiplier: u32, divisor: $primitive_type, } impl $struct_name { /// Creates a new divisor instance. /// /// If possible, avoid calling new() from an inner loop: The intended usage is to create an instance of this struct outside the loop, and use it for divison and remainders inside the loop. /// /// # Panics: /// /// Panics if `divisor` is 0 #[inline] pub fn new(divisor: $primitive_type) -> Self { assert!(divisor > 0); if divisor.is_power_of_two() { Self{ multiplier: 0, divisor } } else { let divided = core::u32::MAX / (divisor as u32); Self{ multiplier: divided + 1, divisor } } } /// Simultaneous truncated integer division and modulus. /// Returns `(quotient, remainder)`. #[inline] pub fn div_rem(numerator: $primitive_type, denom: Self) -> ($primitive_type, $primitive_type) { let quotient = numerator / denom; let remainder = numerator - quotient * denom.divisor; (quotient, remainder) } /// Retrieve the value used to create this struct #[inline] pub fn get(&self) -> $primitive_type { self.divisor } } impl Div<$struct_name> for $primitive_type { type Output = $primitive_type; #[inline] fn div(self, rhs: $struct_name) -> Self::Output { if rhs.multiplier == 0 { self >> rhs.divisor.trailing_zeros() } else { let numerator = self as u32; let multiplied_hi = numerator * (rhs.multiplier >> 16); let multiplied_lo = (numerator * rhs.multiplier as u16 as u32) >> 16; ((multiplied_hi + multiplied_lo) >> 16) as $primitive_type } } } impl Rem<$struct_name> for $primitive_type { type Output = $primitive_type; #[inline] fn rem(self, rhs: $struct_name) -> Self::Output { if rhs.multiplier == 0 { self & (rhs.divisor - 1) } else { let quotient = self / rhs; self - quotient * rhs.divisor } } } ) } // small types prefer to do work in the intermediate type macro_rules! strength_reduced_u32 { ($struct_name:ident, $primitive_type:ident) => ( /// Implements unsigned division and modulo via mutiplication and shifts. /// /// Creating a an instance of this struct is more expensive than a single division, but if the division is repeated, /// this version will be several times faster than naive division. #[derive(Clone, Copy, Debug)] pub struct $struct_name { multiplier: u64, divisor: $primitive_type, } impl $struct_name { /// Creates a new divisor instance. /// /// If possible, avoid calling new() from an inner loop: The intended usage is to create an instance of this struct outside the loop, and use it for divison and remainders inside the loop. /// /// # Panics: /// /// Panics if `divisor` is 0 #[inline] pub fn new(divisor: $primitive_type) -> Self { assert!(divisor > 0); if divisor.is_power_of_two() { Self{ multiplier: 0, divisor } } else { let divided = core::u64::MAX / (divisor as u64); Self{ multiplier: divided + 1, divisor } } } /// Simultaneous truncated integer division and modulus. /// Returns `(quotient, remainder)`. #[inline] pub fn div_rem(numerator: $primitive_type, denom: Self) -> ($primitive_type, $primitive_type) { if denom.multiplier == 0 { (numerator >> denom.divisor.trailing_zeros(), numerator & (denom.divisor - 1)) } else { let numerator64 = numerator as u64; let multiplied_hi = numerator64 * (denom.multiplier >> 32); let multiplied_lo = numerator64 * (denom.multiplier as u32 as u64) >> 32; let quotient = ((multiplied_hi + multiplied_lo) >> 32) as $primitive_type; let remainder = numerator - quotient * denom.divisor; (quotient, remainder) } } /// Retrieve the value used to create this struct #[inline] pub fn get(&self) -> $primitive_type { self.divisor } } impl Div<$struct_name> for $primitive_type { type Output = $primitive_type; #[inline] fn div(self, rhs: $struct_name) -> Self::Output { if rhs.multiplier == 0 { self >> rhs.divisor.trailing_zeros() } else { let numerator = self as u64; let multiplied_hi = numerator * (rhs.multiplier >> 32); let multiplied_lo = numerator * (rhs.multiplier as u32 as u64) >> 32; ((multiplied_hi + multiplied_lo) >> 32) as $primitive_type } } } impl Rem<$struct_name> for $primitive_type { type Output = $primitive_type; #[inline] fn rem(self, rhs: $struct_name) -> Self::Output { if rhs.multiplier == 0 { self & (rhs.divisor - 1) } else { let product = rhs.multiplier.wrapping_mul(self as u64) as u128; let divisor = rhs.divisor as u128; let shifted = (product * divisor) >> 64; shifted as $primitive_type } } } ) } macro_rules! strength_reduced_u64 { ($struct_name:ident, $primitive_type:ident) => ( /// Implements unsigned division and modulo via mutiplication and shifts. /// /// Creating a an instance of this struct is more expensive than a single division, but if the division is repeated, /// this version will be several times faster than naive division. #[derive(Clone, Copy, Debug)] pub struct $struct_name { multiplier: u128, divisor: $primitive_type, } impl $struct_name { /// Creates a new divisor instance. /// /// If possible, avoid calling new() from an inner loop: The intended usage is to create an instance of this struct outside the loop, and use it for divison and remainders inside the loop. /// /// # Panics: /// /// Panics if `divisor` is 0 #[inline] pub fn new(divisor: $primitive_type) -> Self { assert!(divisor > 0); if divisor.is_power_of_two() { Self{ multiplier: 0, divisor } } else { let quotient = long_division::divide_128_max_by_64(divisor as u64); Self{ multiplier: quotient + 1, divisor } } } /// Simultaneous truncated integer division and modulus. /// Returns `(quotient, remainder)`. #[inline] pub fn div_rem(numerator: $primitive_type, denom: Self) -> ($primitive_type, $primitive_type) { if denom.multiplier == 0 { (numerator >> denom.divisor.trailing_zeros(), numerator & (denom.divisor - 1)) } else { let numerator128 = numerator as u128; let multiplied_hi = numerator128 * (denom.multiplier >> 64); let multiplied_lo = numerator128 * (denom.multiplier as u64 as u128) >> 64; let quotient = ((multiplied_hi + multiplied_lo) >> 64) as $primitive_type; let remainder = numerator - quotient * denom.divisor; (quotient, remainder) } } /// Retrieve the value used to create this struct #[inline] pub fn get(&self) -> $primitive_type { self.divisor } } impl Div<$struct_name> for $primitive_type { type Output = $primitive_type; #[inline] fn div(self, rhs: $struct_name) -> Self::Output { if rhs.multiplier == 0 { self >> rhs.divisor.trailing_zeros() } else { let numerator = self as u128; let multiplied_hi = numerator * (rhs.multiplier >> 64); let multiplied_lo = numerator * (rhs.multiplier as u64 as u128) >> 64; ((multiplied_hi + multiplied_lo) >> 64) as $primitive_type } } } impl Rem<$struct_name> for $primitive_type { type Output = $primitive_type; #[inline] fn rem(self, rhs: $struct_name) -> Self::Output { if rhs.multiplier == 0 { self & (rhs.divisor - 1) } else { let quotient = self / rhs; self - quotient * rhs.divisor } } } ) } /// Implements unsigned division and modulo via mutiplication and shifts. /// /// Creating a an instance of this struct is more expensive than a single division, but if the division is repeated, /// this version will be several times faster than naive division. #[derive(Clone, Copy, Debug)] pub struct StrengthReducedU128 { multiplier_hi: u128, multiplier_lo: u128, divisor: u128, } impl StrengthReducedU128 { /// Creates a new divisor instance. /// /// If possible, avoid calling new() from an inner loop: The intended usage is to create an instance of this struct outside the loop, and use it for divison and remainders inside the loop. /// /// # Panics: /// /// Panics if `divisor` is 0 #[inline] pub fn new(divisor: u128) -> Self { assert!(divisor > 0); if divisor.is_power_of_two() { Self{ multiplier_hi: 0, multiplier_lo: 0, divisor } } else { let (quotient_hi, quotient_lo) = long_division::divide_256_max_by_128(divisor); let multiplier_lo = quotient_lo.wrapping_add(1); let multiplier_hi = if multiplier_lo == 0 { quotient_hi + 1 } else { quotient_hi }; Self{ multiplier_hi, multiplier_lo, divisor } } } /// Simultaneous truncated integer division and modulus. /// Returns `(quotient, remainder)`. #[inline] pub fn div_rem(numerator: u128, denom: Self) -> (u128, u128) { let quotient = numerator / denom; let remainder = numerator - quotient * denom.divisor; (quotient, remainder) } /// Retrieve the value used to create this struct #[inline] pub fn get(&self) -> u128 { self.divisor } } impl Div for u128 { type Output = u128; #[inline] fn div(self, rhs: StrengthReducedU128) -> Self::Output { if rhs.multiplier_hi == 0 { self >> rhs.divisor.trailing_zeros() } else { long_multiplication::multiply_256_by_128_upperbits(rhs.multiplier_hi, rhs.multiplier_lo, self) } } } impl Rem for u128 { type Output = u128; #[inline] fn rem(self, rhs: StrengthReducedU128) -> Self::Output { if rhs.multiplier_hi == 0 { self & (rhs.divisor - 1) } else { let quotient = long_multiplication::multiply_256_by_128_upperbits(rhs.multiplier_hi, rhs.multiplier_lo, self); self - quotient * rhs.divisor } } } // We just hardcoded u8 and u128 since they will never be a usize. for the rest, we have macros, so we can reuse the same code for usize strength_reduced_u16!(StrengthReducedU16, u16); strength_reduced_u32!(StrengthReducedU32, u32); strength_reduced_u64!(StrengthReducedU64, u64); // Our definition for usize will depend on how big usize is #[cfg(target_pointer_width = "16")] strength_reduced_u16!(StrengthReducedUsize, usize); #[cfg(target_pointer_width = "32")] strength_reduced_u32!(StrengthReducedUsize, usize); #[cfg(target_pointer_width = "64")] strength_reduced_u64!(StrengthReducedUsize, usize); #[cfg(test)] mod unit_tests { use super::*; macro_rules! reduction_test { ($test_name:ident, $struct_name:ident, $primitive_type:ident) => ( #[test] fn $test_name() { let max = core::$primitive_type::MAX; let divisors = [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,max-1,max]; let numerators = [0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20]; for &divisor in &divisors { let reduced_divisor = $struct_name::new(divisor); for &numerator in &numerators { let expected_div = numerator / divisor; let expected_rem = numerator % divisor; let reduced_div = numerator / reduced_divisor; assert_eq!(expected_div, reduced_div, "Divide failed with numerator: {}, divisor: {}", numerator, divisor); let reduced_rem = numerator % reduced_divisor; let (reduced_combined_div, reduced_combined_rem) = $struct_name::div_rem(numerator, reduced_divisor); assert_eq!(expected_rem, reduced_rem, "Modulo failed with numerator: {}, divisor: {}", numerator, divisor); assert_eq!(expected_div, reduced_combined_div, "div_rem divide failed with numerator: {}, divisor: {}", numerator, divisor); assert_eq!(expected_rem, reduced_combined_rem, "div_rem modulo failed with numerator: {}, divisor: {}", numerator, divisor); } } } ) } reduction_test!(test_strength_reduced_u8, StrengthReducedU8, u8); reduction_test!(test_strength_reduced_u16, StrengthReducedU16, u16); reduction_test!(test_strength_reduced_u32, StrengthReducedU32, u32); reduction_test!(test_strength_reduced_u64, StrengthReducedU64, u64); reduction_test!(test_strength_reduced_usize, StrengthReducedUsize, usize); reduction_test!(test_strength_reduced_u128, StrengthReducedU128, u128); } strength_reduce-0.2.4/src/long_division.rs000064400000000000000000000624630072674642500170570ustar 00000000000000extern crate core; const U32_MAX: u64 = core::u32::MAX as u64; const U64_MAX: u128 = core::u64::MAX as u128; use ::StrengthReducedU64; use ::long_multiplication; // divides a 128-bit number by a 64-bit divisor, returning the quotient as a 64-bit number // assumes that the divisor and numerator have both already been bit-shifted so that divisor.leading_zeros() == 0 #[inline] fn divide_128_by_64_preshifted(numerator_hi: u64, numerator_lo: u64, divisor: u64) -> u64 { let numerator_mid = (numerator_lo >> 32) as u128; let numerator_lo = numerator_lo as u32 as u128; let divisor_full_128 = divisor as u128; let divisor_hi = divisor >> 32; // To get the upper 32 bits of the quotient, we want to divide 'full_upper_numerator' by 'divisor' // but the problem is, full_upper_numerator is a 96-bit number, meaning we would need to use u128 to do the division all at once, and the whole point of this is that we don't want to do 128 bit divison because it's slow // so instead, we'll shift both the numerator and divisor right by 32, giving us a 64 bit / 32 bit division. This won't give us the exact quotient -- but it will be close. let full_upper_numerator = ((numerator_hi as u128) << 32) | numerator_mid; let mut quotient_hi = core::cmp::min(numerator_hi / divisor_hi, U32_MAX); let mut product_hi = quotient_hi as u128 * divisor_full_128; // quotient_hi contains our guess at what the quotient is! the problem is that we got this by ignoring the lower 32 bits of the divisor. when we account for that, the quotient might be slightly lower // we will know our quotient is too high if quotient * divisor > numerator. if it is, decrement until it's in range while product_hi > full_upper_numerator { quotient_hi -= 1; product_hi -= divisor_full_128; } let remainder_hi = full_upper_numerator - product_hi; // repeat the process using the lower half of the numerator let full_lower_numerator = (remainder_hi << 32) | numerator_lo; let mut quotient_lo = core::cmp::min((remainder_hi as u64) / divisor_hi, U32_MAX); let mut product_lo = quotient_lo as u128 * divisor_full_128; // again, quotient_lo is just a guess at this point, it might be slightly too large while product_lo > full_lower_numerator { quotient_lo -= 1; product_lo -= divisor_full_128; } // We now have our separate quotients, now we just have to add them together (quotient_hi << 32) | quotient_lo } // divides a 128-bit number by a 64-bit divisor, returning the quotient as a 64-bit number // assumes that the divisor and numerator have both already been bit-shifted to maximize the number of bits in divisor_hi // divisor_hi should be the upper 32 bits, and divisor_lo should be the lower 32 bits #[inline] fn divide_128_by_64_preshifted_reduced(numerator_hi: u64, numerator_lo: u64, divisor_hi: StrengthReducedU64, divisor_full: u64) -> u64 { let numerator_mid = (numerator_lo >> 32) as u128; let numerator_lo = numerator_lo as u32 as u128; let divisor_full_128 = divisor_full as u128; // To get the upper 32 bits of the quotient, we want to divide 'full_upper_numerator' by 'divisor' // but the problem is, full_upper_numerator is a 96-bit number, meaning we would need to use u128 to do the division all at once, and the whole point of this is that we don't want to do 128 bit divison because it's slow // so instead, we'll shift both the numerator and divisor right by 32, giving us a 64 bit / 32 bit division. This won't give us the exact quotient -- but it will be close. let full_upper_numerator = ((numerator_hi as u128) << 32) | numerator_mid; let mut quotient_hi = core::cmp::min(numerator_hi / divisor_hi, U32_MAX); let mut product_hi = quotient_hi as u128 * divisor_full_128; // quotient_hi contains our guess at what the quotient is! the problem is that we got this by ignoring the lower 32 bits of the divisor. when we account for that, the quotient might be slightly lower // we will know our quotient is too high if quotient * divisor > numerator. if it is, decrement until it's in range while product_hi > full_upper_numerator { quotient_hi -= 1; product_hi -= divisor_full_128; } let full_upper_remainder = full_upper_numerator - product_hi; // repeat the process using the lower half of the numerator let full_lower_numerator = (full_upper_remainder << 32) | numerator_lo; let mut quotient_lo = core::cmp::min((full_upper_remainder as u64) / divisor_hi, U32_MAX); let mut product_lo = quotient_lo as u128 * divisor_full_128; // again, quotient_lo is just a guess at this point, it might be slightly too large while product_lo > full_lower_numerator { quotient_lo -= 1; product_lo -= divisor_full_128; } // We now have our separate quotients, now we just have to add them together (quotient_hi << 32) | quotient_lo } // divides a 128-bit number by a 128-bit divisor pub fn divide_128(numerator: u128, divisor: u128) -> u128 { if divisor <= U64_MAX { let divisor64 = divisor as u64; let upper_numerator = (numerator >> 64) as u64; if divisor64 > upper_numerator { divide_128_by_64_helper(numerator, divisor64) as u128 } else { let upper_quotient = upper_numerator / divisor64; let upper_remainder = upper_numerator - upper_quotient * divisor64; let intermediate_numerator = ((upper_remainder as u128) << 64) | (numerator as u64 as u128); let lower_quotient = divide_128_by_64_helper(intermediate_numerator, divisor64); ((upper_quotient as u128) << 64) | (lower_quotient as u128) } } else { let shift_size = divisor.leading_zeros(); let shifted_divisor = divisor << shift_size; let shifted_numerator = numerator >> 1; let upper_quotient = divide_128_by_64_helper(shifted_numerator, (shifted_divisor >> 64) as u64); let mut quotient = upper_quotient >> (63 - shift_size); if quotient > 0 { quotient -= 1; } let remainder = numerator - quotient as u128 * divisor; if remainder >= divisor { quotient += 1; } quotient as u128 } } // divides a 128-bit number by a 64-bit divisor, returning the quotient as a 64-bit number. Panics if the quotient doesn't fit in a 64-bit number fn divide_128_by_64_helper(numerator: u128, divisor: u64) -> u64 { // Assert that the upper half of the numerator is less than the denominator. This will guarantee that the quotient fits inside the numerator. // Sadly this will give us some false negatives! TODO: Find a quick test we can do that doesn't have false negatives // false negative example: numerator = u64::MAX * u64::MAX / u64::MAX assert!(divisor > (numerator >> 64) as u64, "The numerator is too large for the denominator; the quotient might not fit inside a u64."); if divisor <= U32_MAX { return divide_128_by_32_helper(numerator, divisor as u32); } let shift_size = divisor.leading_zeros(); let shifted_divisor = divisor << shift_size; let shifted_numerator = numerator << shift_size; let divisor_hi = shifted_divisor >> 32; let divisor_lo = shifted_divisor as u32 as u64; // split the numerator into 3 chunks: the top 64-bits, the next 32-bits, and the lowest 32-bits let numerator_hi : u64 = (shifted_numerator >> 64) as u64; let numerator_mid : u64 = (shifted_numerator >> 32) as u32 as u64; let numerator_lo : u64 = shifted_numerator as u32 as u64; // we're essentially going to do a long division algorithm with 2 divisions, one on numerator_hi << 32 | numerator_mid, and the second on the remainder of the first | numerator_lo // but numerator_hi << 32 | numerator_mid is a 96-bit number, and we only have 64 bits to work with. so instead we split the divisor into 2 chunks, and divde by the upper chunk, and then check against the lower chunk in a while loop // step 1: divide the top chunk of the numerator by the divisor // IDEALLY, we would divide (numerator_hi << 32) | numerator_mid by shifted_divisor, but that would require a 128-bit numerator, which is the whole thing we're trying to avoid // so instead we're going to split the second division into two sub-phases. in 1a, we divide numerator_hi by divisor_hi, and then in 1b we decrement the quotient to account for the fact that it'll be smaller when you take divisor_lo into account // keep in mind that for all of step 2, the full numerator we're using will be // complete_first_numerator = (numerator_midbits << 32) | numerator_mid // step 1a: divide the upper part of the middle numerator by the upper part of the divisor let mut quotient_hi = core::cmp::min(numerator_hi / divisor_hi, U32_MAX); let mut partial_remainder_hi = numerator_hi - quotient_hi * divisor_hi; // step 1b: we know sort of what the quotient is, but it's slightly too large because it doesn't account for divisor_lo, nor numerator_mid, so decrement the quotient until it fits // note that if we do some algebra on the condition in this while loop, // ie "quotient_hi * divisor_lo > (partial_remainder_hi << 32) | numerator_mid" // we end up getting "quotient_hi * shifted_divisor < (numerator_midbits << 32) | numerator_mid". remember that the right side of the inequality sign is complete_first_numerator from above. // which deminstrates that we're decrementing the quotient until the quotient multipled by the complete divisor is less than the complete numerator while partial_remainder_hi <= U32_MAX && quotient_hi * divisor_lo > (partial_remainder_hi << 32) | numerator_mid { quotient_hi -= 1; partial_remainder_hi += divisor_hi; } // step 2: Divide the bottom part of the numerator. We're going to have the same problem as step 1, where we want the numerator to be a 96-bit number, so again we're going to split it into 2 substeps // the full numeratoe for step 3 will be: // complete_second_numerator = (first_division_remainder << 32) | numerator_lo // step 2a: divide the upper part of the lower numerator by the upper part of the divisor // To get the numerator, complate the calculation of the full remainder by subtracing the quotient times the lower bits of the divisor // TODO: a warpping subtract is necessary here. why does this work, and why is it necessary? let full_remainder_hi = ((partial_remainder_hi << 32) | numerator_mid).wrapping_sub(quotient_hi * divisor_lo); let mut quotient_lo = core::cmp::min(full_remainder_hi / divisor_hi, U32_MAX); let mut partial_remainder_lo = full_remainder_hi - quotient_lo * divisor_hi; // step 2b: just like step 1b, decrement the final quotient until it's correctr when accounting for the full divisor while partial_remainder_lo <= U32_MAX && quotient_lo * divisor_lo > (partial_remainder_lo << 32) | numerator_lo { quotient_lo -= 1; partial_remainder_lo += divisor_hi; } // We now have our separate quotients, now we just have to add them together (quotient_hi << 32) | quotient_lo } // Same as divide_128_by_64_into_64, but optimized for scenarios where the divisor fits in a u32. Still panics if the quotient doesn't fit in a u64 fn divide_128_by_32_helper(numerator: u128, divisor: u32) -> u64 { // Assert that the upper half of the numerator is less than the denominator. This will guarantee that the quotient fits inside the numerator. // Sadly this will give us some false negatives! TODO: Find a quick test we can do that doesn't have false negatives // false negative example: numerator = u64::MAX * u64::MAX / u64::MAX assert!(divisor as u64 > (numerator >> 64) as u64, "The numerator is too large for the denominator; the quotient might not fit inside a u64."); let shift_size = divisor.leading_zeros(); let shifted_divisor = (divisor << shift_size) as u64; let shifted_numerator = numerator << (shift_size + 32); // split the numerator into 3 chunks: the top 64-bits, the next 32-bits, and the lowest 32-bits let numerator_hi : u64 = (shifted_numerator >> 64) as u64; let numerator_mid : u64 = (shifted_numerator >> 32) as u32 as u64; // we're essentially going to do a long division algorithm with 2 divisions, one on numerator_hi << 32 | numerator_mid, and the second on the remainder of the first | numerator_lo // but numerator_hi << 32 | numerator_mid is a 96-bit number, and we only have 64 bits to work with. so instead we split the divisor into 2 chunks, and divde by the upper chunk, and then check against the lower chunk in a while loop // step 1: divide the top chunk of the numerator by the divisor // IDEALLY, we would divide (numerator_hi << 32) | numerator_mid by shifted_divisor, but that would require a 128-bit numerator, which is the whole thing we're trying to avoid // so instead we're going to split the second division into two sub-phases. in 1a, we divide numerator_hi by divisor_hi, and then in 1b we decrement the quotient to account for the fact that it'll be smaller when you take divisor_lo into account // keep in mind that for all of step 1, the full numerator we're using will be // complete_first_numerator = (numerator_hi << 32) | numerator_mid // step 1a: divide the upper part of the middle numerator by the upper part of the divisor let quotient_hi = numerator_hi / shifted_divisor; let remainder_hi = numerator_hi - quotient_hi * shifted_divisor; // step 2: Divide the bottom part of the numerator. We're going to have the same problem as step 1, where we want the numerator to be a 96-bit number, so again we're going to split it into 2 substeps // the full numeratoe for step 3 will be: // complete_second_numerator = (first_division_remainder << 32) | numerator_lo // step 2a: divide the upper part of the lower numerator by the upper part of the divisor // To get the numerator, complate the calculation of the full remainder by subtracing the quotient times the lower bits of the divisor // TODO: a warpping subtract is necessary here. why does this work, and why is it necessary? let final_numerator = (remainder_hi) << 32 | numerator_mid; let quotient_lo = final_numerator / shifted_divisor; // We now have our separate quotients, now we just have to add them together (quotient_hi << 32) | quotient_lo } #[inline(never)] fn long_division(numerator_slice: &[u64], reduced_divisor: &StrengthReducedU64, quotient: &mut [u64]) { let mut remainder = 0; for (numerator_element, quotient_element) in numerator_slice.iter().zip(quotient.iter_mut()).rev() { if remainder > 0 { // Do one division that includes the running remainder and the upper half of this numerator element, // then a second division for the first division's remainder combinedwith the lower half let upper_numerator = (remainder << 32) | (*numerator_element >> 32); let (upper_quotient, upper_remainder) = StrengthReducedU64::div_rem(upper_numerator, *reduced_divisor); let lower_numerator = (upper_remainder << 32) | (*numerator_element as u32 as u64); let (lower_quotient, lower_remainder) = StrengthReducedU64::div_rem(lower_numerator, *reduced_divisor); *quotient_element = (upper_quotient << 32) | lower_quotient; remainder = lower_remainder; } else { // The remainder is zero, which means we can take a shortcut and only do a single division! let (digit_quotient, digit_remainder) = StrengthReducedU64::div_rem(*numerator_element, *reduced_divisor); *quotient_element = digit_quotient; remainder = digit_remainder; } } } #[inline] fn normalize_slice(input: &mut [u64]) -> &mut [u64] { let input_len = input.len(); let trailing_zero_chunks = input.iter().rev().take_while(|e| **e == 0).count(); &mut input[..input_len - trailing_zero_chunks] } #[inline] fn is_slice_greater(a: &[u64], b: &[u64]) -> bool { if a.len() > b.len() { return true; } if b.len() > a.len() { return false; } for (&ai, &bi) in a.iter().zip(b.iter()).rev() { if ai < bi { return false; } if ai > bi { return true; } } false } // subtract b from a, and store the result in a #[inline] fn sub_assign(a: &mut [u64], b: &[u64]) { let mut borrow: i128 = 0; // subtract b from a, keeping track of borrows as we go let (a_lo, a_hi) = a.split_at_mut(b.len()); for (a, b) in a_lo.iter_mut().zip(b) { borrow += *a as i128; borrow -= *b as i128; *a = borrow as u64; borrow >>= 64; } // We're done subtracting, we just need to finish carrying let mut a_element = a_hi.iter_mut(); while borrow != 0 { let a_element = a_element.next().expect("borrow underflow during sub_assign"); borrow += *a_element as i128; *a_element = borrow as u64; borrow >>= 64; } } pub(crate) fn divide_128_max_by_64(divisor: u64) -> u128 { let quotient_hi = core::u64::MAX / divisor; let remainder_hi = core::u64::MAX - quotient_hi * divisor; let leading_zeros = divisor.leading_zeros(); let quotient_lo = if leading_zeros >= 32 { let numerator_mid = (remainder_hi << 32) | core::u32::MAX as u64; let quotient_mid = numerator_mid / divisor; let remainder_mid = numerator_mid - quotient_mid * divisor; let numerator_lo = (remainder_mid << 32) | core::u32::MAX as u64; let quotient_lo = numerator_lo / divisor; (quotient_mid << 32) | quotient_lo } else { let numerator_hi = if leading_zeros > 0 { (remainder_hi << leading_zeros) | (core::u64::MAX >> (64 - leading_zeros)) } else { remainder_hi }; let numerator_lo = core::u64::MAX << leading_zeros; divide_128_by_64_preshifted(numerator_hi, numerator_lo, divisor << leading_zeros) }; ((quotient_hi as u128) << 64) | (quotient_lo as u128) } fn divide_256_max_by_32(divisor: u32) -> (u128, u128) { let reduced_divisor = StrengthReducedU64::new(divisor as u64); let mut numerator_chunks = [core::u64::MAX; 4]; let mut quotient_chunks = [0; 4]; long_division(&mut numerator_chunks, &reduced_divisor, &mut quotient_chunks); // quotient_chunks now contains the quotient! all we have to do is recombine it into u128s let quotient_lo = (quotient_chunks[0] as u128) | ((quotient_chunks[1] as u128) << 64); let quotient_hi = (quotient_chunks[2] as u128) | ((quotient_chunks[3] as u128) << 64); (quotient_hi, quotient_lo) } pub(crate) fn divide_256_max_by_128(divisor: u128) -> (u128, u128) { let leading_zeros = divisor.leading_zeros(); // if the divisor fits inside a u32, we can use a much faster algorithm if leading_zeros >= 96 { return divide_256_max_by_32(divisor as u32); } let empty_divisor_chunks = (leading_zeros / 64) as usize; let shift_amount = leading_zeros % 64; // Shift the divisor and chunk it up into U32s let divisor_shifted = divisor << shift_amount; let divisor_chunks = [ divisor_shifted as u64, (divisor_shifted >> 64) as u64, ]; let divisor_slice = &divisor_chunks[..(divisor_chunks.len() - empty_divisor_chunks)]; // We're gonna be doing a ton of u64/u64 divisions, so we're gonna eat our own dog food and set up a strength-reduced division instance // the only actual **divisions* we'll be doing will be with the largest 32 bits of the full divisor, not the full divisor let reduced_divisor_hi = StrengthReducedU64::new(*divisor_slice.last().unwrap() >> 32); let divisor_hi = *divisor_slice.last().unwrap(); // Build our numerator, represented by u32 chunks. at first it will be full of u32::MAX, but we will iteratively take chunks out of it as we divide let mut numerator_chunks = [core::u64::MAX; 5]; let mut numerator_max_idx = if shift_amount > 0 { numerator_chunks[4] >>= 64 - shift_amount; numerator_chunks[0] <<= shift_amount; 5 } else { 4 }; // allocate the biggest-possible quotient, even if it might be smaller -- we just won't fill out the biggest parts let num_quotient_chunks = 3 + empty_divisor_chunks; let mut quotient_chunks = [0; 4]; for quotient_idx in (0..num_quotient_chunks).rev() { /* * When calculating our next guess q0, we don't need to consider the digits below j * + b.data.len() - 1: we're guessing digit j of the quotient (i.e. q0 << j) from * digit bn of the divisor (i.e. bn << (b.data.len() - 1) - so the product of those * two numbers will be zero in all digits up to (j + b.data.len() - 1). */ let numerator_slice = &mut numerator_chunks[..numerator_max_idx]; let numerator_start_idx = quotient_idx + divisor_slice.len() - 1; if numerator_start_idx >= numerator_slice.len() { continue; } // scope for borrow checker { // divide the uppermost bits of the remaining numerator to get "sub_quotient" which will be our guess for this quotient element let numerator_hi = if numerator_slice.len() - numerator_start_idx > 1 { numerator_slice[numerator_start_idx + 1] } else { 0 }; let numerator_lo = numerator_slice[numerator_start_idx]; let mut sub_quotient = divide_128_by_64_preshifted_reduced(numerator_hi, numerator_lo, reduced_divisor_hi, divisor_hi); let mut tmp_product = [0; 3]; long_multiplication::long_multiply(&divisor_slice, sub_quotient, &mut tmp_product); let sub_product = normalize_slice(&mut tmp_product); // our sub_quotient is just a guess at the quotient -- it only accounts for the topmost bits of the divisor. when we take the bottom bits of the divisor into account, the actual quotient will be smaller // we will know if our guess is too large if (quotient_guess * full_divisor) (aka sub_product) is greater than this iteration's numerator slice. ifthat's the case, decrement it until it's less than or equal. while is_slice_greater(sub_product, &numerator_slice[quotient_idx..]) { sub_assign(sub_product, &divisor_slice); sub_quotient -= 1; } // sub_quotient is now the correct sub-quotient for this iteration. add it to the full quotient, and subtract the product from the full numerator, so that what remains in the numerator is the remainder of this division quotient_chunks[quotient_idx] = sub_quotient; sub_assign(&mut numerator_slice[quotient_idx..], sub_product); } // slice off any zeroes at the end of the numerator. we're not calling normalize_slice here because of borrow checker obnoxiousness numerator_max_idx -= numerator_slice.iter().rev().take_while(|e| **e == 0).count(); } // quotient_chunks now contains the quotient! all we have to do is recombine it into u128s let quotient_lo = (quotient_chunks[0] as u128) | ((quotient_chunks[1] as u128) << 64); let quotient_hi = (quotient_chunks[2] as u128) | ((quotient_chunks[3] as u128) << 64); (quotient_hi, quotient_lo) } #[cfg(test)] mod unit_tests { use num_bigint::BigUint; #[test] fn test_divide_128_by_64() { for divisor in core::u64::MAX..=core::u64::MAX { let divisor_128 = core::u64::MAX as u128; let numerator = divisor_128 * divisor_128 + (divisor_128 - 1); //for numerator in core::u128::MAX - 10..core::u128::MAX { let expected_quotient = numerator / divisor as u128; assert!(expected_quotient == core::u64::MAX as u128); let actual_quotient = super::divide_128_by_64_helper(numerator as u128, divisor); let expected_upper = (expected_quotient >> 32) as u64; let expected_lower = expected_quotient as u32 as u64; let actual_upper = (actual_quotient >> 32) as u64; let actual_lower = actual_quotient as u32 as u64; assert_eq!(expected_upper, actual_upper, "wrong quotient for {}/{}", numerator, divisor); assert_eq!(expected_lower, actual_lower, "wrong quotient for {}/{}", numerator, divisor); //} } } fn test_divisor_128(divisor: u128) { let big_numerator = BigUint::from_slice(&[core::u32::MAX; 8]); let big_quotient = big_numerator / divisor; //let (actual_hi, actual_lo) = super::divide_256_max_by_128_direct(divisor); let (actual64_hi, actual64_lo) = super::divide_256_max_by_128(divisor); //let actual_big = (BigUint::from(actual_hi) << 128) | BigUint::from(actual_lo); let actual64_big = (BigUint::from(actual64_hi) << 128) | BigUint::from(actual64_lo); //assert_eq!(big_quotient, actual_big, "Actual quotient didn't match expected quotient for max/{}", divisor); assert_eq!(big_quotient, actual64_big, "Actual64 quotient didn't match expected quotient for max/{}", divisor); } #[allow(unused_imports)] use rand::{rngs::StdRng, SeedableRng, distributions::Distribution, distributions::Uniform}; #[test] fn test_max_256() { let log2_tests_per_bit = 6; for divisor in 1..(1 << log2_tests_per_bit) { test_divisor_128(divisor); } let mut gen = StdRng::seed_from_u64(5673573); for bits in log2_tests_per_bit..128 { let lower_start = 1 << bits; let lower_stop = lower_start + (1 << (log2_tests_per_bit - 3)); let upper_stop = 1u128.checked_shl(bits + 1).map_or(core::u128::MAX, |v| v - 1); let upper_start = upper_stop - (1 << (log2_tests_per_bit - 3)) + 1; for divisor in lower_start..lower_stop { test_divisor_128(divisor); } for divisor in upper_start..=upper_stop { test_divisor_128(divisor); } let random_count = 1 << log2_tests_per_bit; let dist = Uniform::new(lower_stop + 1, upper_start); for _ in 0..random_count { let divisor = dist.sample(&mut gen); test_divisor_128(divisor); } } } } strength_reduce-0.2.4/src/long_multiplication.rs000064400000000000000000000054060072674642500202620ustar 00000000000000 // multiply the 256-bit number 'a' by the 128-bit number 'b' and return the uppermost 128 bits of the product // ripped directly from num-biguint's long multiplication algorithm (mac3, mac_with_carry, adc), but with fixed-size arrays instead of slices #[inline] pub(crate) fn multiply_256_by_128_upperbits(a_hi: u128, a_lo: u128, b: u128) -> u128 { // Break a and b into little-endian 64-bit chunks let a_chunks = [ a_lo as u64, (a_lo >> 64) as u64, a_hi as u64, (a_hi >> 64) as u64, ]; let b_chunks = [ b as u64, (b >> 64) as u64, ]; // Multiply b by a, one chink of b at a time let mut product = [0; 6]; for (b_index, &b_digit) in b_chunks.iter().enumerate() { multiply_256_by_64_helper(&mut product[b_index..], &a_chunks, b_digit); } // the last 2 elements of the array have the part of the productthat we care about ((product[5] as u128) << 64) | (product[4] as u128) } #[inline] fn multiply_256_by_64_helper(product: &mut [u64], a: &[u64;4], b: u64) { if b == 0 { return; } let mut carry = 0; let (product_lo, product_hi) = product.split_at_mut(a.len()); // Multiply each of the digits in a by b, adding them into the 'product' value. // We don't zero out product, because we this will be called multiple times, so it probably contains a previous iteration's partial product, and we're adding + carrying on top of it for (p, &a_digit) in product_lo.iter_mut().zip(a) { carry += *p as u128; carry += (a_digit as u128) * (b as u128); *p = carry as u64; carry >>= 64; } // We're done multiplying, we just need to finish carrying through the rest of the product. let mut p = product_hi.iter_mut(); while carry != 0 { let p = p.next().expect("carry overflow during multiplication!"); carry += *p as u128; *p = carry as u64; carry >>= 64; } } // compute product += a * b #[inline] pub(crate) fn long_multiply(a: &[u64], b: u64, product: &mut [u64]) { if b == 0 { return; } let mut carry = 0; let (product_lo, product_hi) = product.split_at_mut(a.len()); // Multiply each of the digits in a by b, adding them into the 'product' value. // We don't zero out product, because we this will be called multiple times, so it probably contains a previous iteration's partial product, and we're adding + carrying on top of it for (p, &a_digit) in product_lo.iter_mut().zip(a) { carry += *p as u128; carry += (a_digit as u128) * (b as u128); *p = carry as u64; carry >>= 64; } // We're done multiplying, we just need to finish carrying through the rest of the product. let mut p = product_hi.iter_mut(); while carry != 0 { let p = p.next().expect("carry overflow during multiplication!"); carry += *p as u128; *p = carry as u64; carry >>= 64; } } strength_reduce-0.2.4/tests/test_reduced_unsigned.rs000064400000000000000000000110540072674642500211230ustar 00000000000000#[macro_use] extern crate proptest; extern crate strength_reduce; use proptest::test_runner::Config; use strength_reduce::{StrengthReducedU8, StrengthReducedU16, StrengthReducedU32, StrengthReducedU64, StrengthReducedUsize, StrengthReducedU128}; macro_rules! reduction_proptest { ($test_name:ident, $struct_name:ident, $primitive_type:ident) => ( mod $test_name { use super::*; use proptest::sample::select; fn assert_div_rem_equivalence(divisor: $primitive_type, numerator: $primitive_type) { let reduced_divisor = $struct_name::new(divisor); let expected_div = numerator / divisor; let expected_rem = numerator % divisor; let reduced_div = numerator / reduced_divisor; let reduced_rem = numerator % reduced_divisor; assert_eq!(expected_div, reduced_div, "Divide failed with numerator: {}, divisor: {}", numerator, divisor); assert_eq!(expected_rem, reduced_rem, "Modulo failed with numerator: {}, divisor: {}", numerator, divisor); let (reduced_combined_div, reduced_combined_rem) = $struct_name::div_rem(numerator, reduced_divisor); assert_eq!(expected_div, reduced_combined_div, "div_rem divide failed with numerator: {}, divisor: {}", numerator, divisor); assert_eq!(expected_rem, reduced_combined_rem, "div_rem modulo failed with numerator: {}, divisor: {}", numerator, divisor); } proptest! { #![proptest_config(Config::with_cases(100_000))] #[test] fn fully_generated_inputs_are_div_rem_equivalent(divisor in 1..core::$primitive_type::MAX, numerator in 0..core::$primitive_type::MAX) { assert_div_rem_equivalence(divisor, numerator); } #[test] fn generated_divisors_with_edge_case_numerators_are_div_rem_equivalent( divisor in 1..core::$primitive_type::MAX, numerator in select(vec![0 as $primitive_type, 1 as $primitive_type, core::$primitive_type::MAX - 1, core::$primitive_type::MAX])) { assert_div_rem_equivalence(divisor, numerator); } #[test] fn generated_numerators_with_edge_case_divisors_are_div_rem_equivalent( divisor in select(vec![1 as $primitive_type, 2 as $primitive_type, core::$primitive_type::MAX - 1, core::$primitive_type::MAX]), numerator in 0..core::$primitive_type::MAX) { assert_div_rem_equivalence(divisor, numerator); } } } ) } reduction_proptest!(strength_reduced_u08, StrengthReducedU8, u8); reduction_proptest!(strength_reduced_u16, StrengthReducedU16, u16); reduction_proptest!(strength_reduced_u32, StrengthReducedU32, u32); reduction_proptest!(strength_reduced_u64, StrengthReducedU64, u64); reduction_proptest!(strength_reduced_usize, StrengthReducedUsize, usize); reduction_proptest!(strength_reduced_u128, StrengthReducedU128, u128); macro_rules! exhaustive_test { ($test_name:ident, $struct_name:ident, $primitive_type:ident) => ( #[test] #[ignore] fn $test_name() { for divisor in 1..=std::$primitive_type::MAX { let reduced_divisor = $struct_name::new(divisor); for numerator in 0..=std::$primitive_type::MAX { let expected_div = numerator / divisor; let expected_rem = numerator % divisor; let reduced_div = numerator / reduced_divisor; assert_eq!(expected_div, reduced_div, "Divide failed with numerator: {}, divisor: {}", numerator, divisor); let reduced_rem = numerator % reduced_divisor; assert_eq!(expected_rem, reduced_rem, "Modulo failed with numerator: {}, divisor: {}", numerator, divisor); let (reduced_combined_div, reduced_combined_rem) = $struct_name::div_rem(numerator, reduced_divisor); assert_eq!(expected_div, reduced_combined_div, "div_rem divide failed with numerator: {}, divisor: {}", numerator, divisor); assert_eq!(expected_rem, reduced_combined_rem, "div_rem modulo failed with numerator: {}, divisor: {}", numerator, divisor); } } } ) } exhaustive_test!(test_strength_reduced_u08_exhaustive, StrengthReducedU8, u8); exhaustive_test!(test_strength_reduced_u16_exhaustive, StrengthReducedU16, u16);