1 // Copyright 2023, The Android Open Source Project
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14
15 //! Utility functions.
16
17 use core::ops::Range;
18
19 /// Flatten [[T; N]] into &[T]
20 /// TODO: use slice::flatten when it graduates from experimental
flatten<T, const N: usize>(original: &[[T; N]]) -> &[T]21 pub fn flatten<T, const N: usize>(original: &[[T; N]]) -> &[T] {
22 // SAFETY: no overflow because original (whose size is len()*N) is already in memory
23 let len = original.len() * N;
24 // SAFETY: [T] has the same layout as [T;N]
25 unsafe { core::slice::from_raw_parts(original.as_ptr().cast(), len) }
26 }
27
28 /// Computes the largest multiple of the provided alignment smaller or equal to the address.
29 ///
30 /// Note: the result is undefined if alignment isn't a power of two.
unchecked_align_down(addr: usize, alignment: usize) -> usize31 pub const fn unchecked_align_down(addr: usize, alignment: usize) -> usize {
32 addr & !(alignment - 1)
33 }
34
35 /// Computes the smallest multiple of the provided alignment larger or equal to the address.
36 ///
37 /// Note: the result is undefined if alignment isn't a power of two and may wrap to 0.
unchecked_align_up(addr: usize, alignment: usize) -> usize38 pub const fn unchecked_align_up(addr: usize, alignment: usize) -> usize {
39 unchecked_align_down(addr + alignment - 1, alignment)
40 }
41
42 /// Safe wrapper around unchecked_align_up() that validates its assumptions and doesn't wrap.
align_up(addr: usize, alignment: usize) -> Option<usize>43 pub const fn align_up(addr: usize, alignment: usize) -> Option<usize> {
44 if !alignment.is_power_of_two() {
45 None
46 } else if let Some(s) = addr.checked_add(alignment - 1) {
47 Some(unchecked_align_down(s, alignment))
48 } else {
49 None
50 }
51 }
52
53 /// Aligns the given address to the given alignment, if it is a power of two.
54 ///
55 /// Returns `None` if the alignment isn't a power of two.
56 #[allow(dead_code)] // Currently unused but might be needed again.
align_down(addr: usize, alignment: usize) -> Option<usize>57 const fn align_down(addr: usize, alignment: usize) -> Option<usize> {
58 if !alignment.is_power_of_two() {
59 None
60 } else {
61 Some(unchecked_align_down(addr, alignment))
62 }
63 }
64
65 /// Performs an integer division rounding up.
66 ///
67 /// Note: Returns None if den isn't a power of two.
ceiling_div(num: usize, den: usize) -> Option<usize>68 pub const fn ceiling_div(num: usize, den: usize) -> Option<usize> {
69 let Some(r) = align_up(num, den) else {
70 return None;
71 };
72
73 r.checked_div(den)
74 }
75
76 /// Trait to check containment of one range within another.
77 pub trait RangeExt {
78 /// Returns true if `self` is contained within the `other` range.
is_within(&self, other: &Self) -> bool79 fn is_within(&self, other: &Self) -> bool;
80
81 /// Returns true if `self` overlaps with the `other` range.
overlaps(&self, other: &Self) -> bool82 fn overlaps(&self, other: &Self) -> bool;
83 }
84
85 impl<T: PartialOrd> RangeExt for Range<T> {
is_within(&self, other: &Self) -> bool86 fn is_within(&self, other: &Self) -> bool {
87 self.start >= other.start && self.end <= other.end
88 }
89
overlaps(&self, other: &Self) -> bool90 fn overlaps(&self, other: &Self) -> bool {
91 self.start < other.end && other.start < self.end
92 }
93 }
94