Struct AddrRange

pub struct AddrRange<A: MemoryAddr> {
    pub start: A,
    pub end: A,
}

A range of a given memory address type A.

The range is inclusive on the start and exclusive on the end. A range is considered empty iff start == end, and invalid iff start > end. An invalid range should not be created and cannot be obtained without unsafe operations, calling methods on an invalid range will cause unexpected consequences.

Example

use memory_addr::AddrRange;

let range = AddrRange::<usize>::new(0x1000, 0x2000);
assert_eq!(range.start, 0x1000);
assert_eq!(range.end, 0x2000);

Fields

start: A

The lower bound of the range (inclusive).

end: A

The upper bound of the range (exclusive).

Implementations

impl<A> AddrRange<A>

where A: MemoryAddr,

Methods for AddrRange.

pub fn new(start: A, end: A) -> Self

Creates a new address range from the start and end addresses.

Panics

Panics if start > end.

Example

use memory_addr::AddrRange;

let range = AddrRange::new(0x1000usize, 0x2000);
assert_eq!(range.start, 0x1000);
assert_eq!(range.end, 0x2000);

And this will panic:

let _ = AddrRange::new(0x2000usize, 0x1000);

pub fn try_new(start: A, end: A) -> Option<Self>

Creates a new address range from the given range.

Returns None if start > end.

Example

use memory_addr::AddrRange;

let range = AddrRange::try_new(0x1000usize, 0x2000).unwrap();
assert_eq!(range.start, 0x1000);
assert_eq!(range.end, 0x2000);
assert!(AddrRange::try_new(0x2000usize, 0x1000).is_none());

pub const unsafe fn new_unchecked(start: A, end: A) -> Self

Creates a new address range from the given range without checking the validity.

Safety

The caller must ensure that start <= end, otherwise the range will be invalid and unexpected consequences will occur.

Example

use memory_addr::AddrRange;

let range = unsafe { AddrRange::new_unchecked(0x1000usize, 0x2000) };
assert_eq!(range.start, 0x1000);
assert_eq!(range.end, 0x2000);

pub fn from_start_size(start: A, size: usize) -> Self

Creates a new address range from the start address and the size.

Panics

Panics if size is too large and causes overflow during evaluating the end address.

Example

use memory_addr::AddrRange;

let range = AddrRange::from_start_size(0x1000usize, 0x1000);
assert_eq!(range.start, 0x1000);
assert_eq!(range.end, 0x2000);

And this will panic:

let _ = AddrRange::from_start_size(0x1000usize, usize::MAX);

pub fn try_from_start_size(start: A, size: usize) -> Option<Self>

Creates a new address range from the start address and the size.

Returns None if size is too large and causes overflow during evaluating the end address.

Example

use memory_addr::AddrRange;

let range = AddrRange::try_from_start_size(0x1000usize, 0x1000).unwrap();
assert_eq!(range.start, 0x1000);
assert_eq!(range.end, 0x2000);
assert!(AddrRange::try_from_start_size(0x1000usize, usize::MAX).is_none());

pub unsafe fn from_start_size_unchecked(start: A, size: usize) -> Self

Creates a new address range from the start address and the size without checking the validity.

Safety

The caller must ensure that size is not too large and won’t cause overflow during evaluating the end address. Failing to do so will create an invalid range and cause unexpected consequences.

Example

use memory_addr::AddrRange;

let range = unsafe { AddrRange::from_start_size_unchecked(0x1000usize, 0x1000) };
assert_eq!(range.start, 0x1000);
assert_eq!(range.end, 0x2000);

pub fn is_empty(self) -> bool

Returns true if the range is empty.

It’s also guaranteed that false will be returned if the range is invalid (i.e., start > end).

Example

use memory_addr::AddrRange;

assert!(AddrRange::new(0x1000usize, 0x1000).is_empty());
assert!(!AddrRange::new(0x1000usize, 0x2000).is_empty());

pub fn size(self) -> usize

Returns the size of the range.

Example

use memory_addr::AddrRange;

assert_eq!(AddrRange::new(0x1000usize, 0x1000).size(), 0);
assert_eq!(AddrRange::new(0x1000usize, 0x2000).size(), 0x1000);

pub fn contains(self, addr: A) -> bool

Checks if the range contains the given address.

Example

use memory_addr::AddrRange;

let range = AddrRange::new(0x1000usize, 0x2000);
assert!(!range.contains(0x0fff));
assert!(range.contains(0x1000));
assert!(range.contains(0x1fff));
assert!(!range.contains(0x2000));

pub fn contains_range(self, other: Self) -> bool

Checks if the range contains the given address range.

Example

use memory_addr::{addr_range, AddrRange};

let range = AddrRange::new(0x1000usize, 0x2000);
assert!(!range.contains_range(addr_range!(0x0usize..0xfff)));
assert!(!range.contains_range(addr_range!(0x0fffusize..0x1fff)));
assert!(range.contains_range(addr_range!(0x1001usize..0x1fff)));
assert!(range.contains_range(addr_range!(0x1000usize..0x2000)));
assert!(!range.contains_range(addr_range!(0x1001usize..0x2001)));
assert!(!range.contains_range(addr_range!(0x2001usize..0x3001)));

pub fn contained_in(self, other: Self) -> bool

Checks if the range is contained in the given address range.

Example

use memory_addr::{addr_range, AddrRange};

let range = AddrRange::new(0x1000usize, 0x2000);
assert!(!range.contained_in(addr_range!(0xfffusize..0x1fff)));
assert!(!range.contained_in(addr_range!(0x1001usize..0x2001)));
assert!(range.contained_in(addr_range!(0xfffusize..0x2001)));
assert!(range.contained_in(addr_range!(0x1000usize..0x2000)));

pub fn overlaps(self, other: Self) -> bool

Checks if the range overlaps with the given address range.

Example

use memory_addr::{addr_range, AddrRange};

let range = AddrRange::new(0x1000usize, 0x2000usize);
assert!(!range.overlaps(addr_range!(0xfffusize..0xfff)));
assert!(!range.overlaps(addr_range!(0x2000usize..0x2000)));
assert!(!range.overlaps(addr_range!(0xfffusize..0x1000)));
assert!(range.overlaps(addr_range!(0xfffusize..0x1001)));
assert!(range.overlaps(addr_range!(0x1fffusize..0x2001)));
assert!(range.overlaps(addr_range!(0xfffusize..0x2001)));

Trait Implementations

impl<A: Clone + MemoryAddr> Clone for AddrRange<A>

fn clone(&self) -> AddrRange<A>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<A> Debug for AddrRange<A>

where A: MemoryAddr + Debug,

Implementations of Debug for AddrRange.

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<A> Default for AddrRange<A>

where A: MemoryAddr,

Implementations of Default for AddrRange.

The default value is an empty range Range { start: 0, end: 0 }.

fn default() -> Self

Returns the “default value” for a type.

impl<A> LowerHex for AddrRange<A>

where A: MemoryAddr + LowerHex,

Implementations of LowerHex for AddrRange.

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<A: PartialEq + MemoryAddr> PartialEq for AddrRange<A>

fn eq(&self, other: &AddrRange<A>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<A, T> TryFrom<Range<T>> for AddrRange<A>

where A: MemoryAddr + From<T>,

Conversion from Range to AddrRange, provided that the type of the endpoints can be converted to the address type A.

type Error = ()

The type returned in the event of a conversion error.

fn try_from(range: Range<T>) -> Result<Self, Self::Error>

Performs the conversion.

impl<A> UpperHex for AddrRange<A>

where A: MemoryAddr + UpperHex,

Implementations of UpperHex for AddrRange.

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<A: Copy + MemoryAddr> Copy for AddrRange<A>

impl<A: Eq + MemoryAddr> Eq for AddrRange<A>

impl<A: MemoryAddr> StructuralPartialEq for AddrRange<A>