imgref_iter/lib.rs
1//! A small crate for iterating over the rows or columns of `imgref` buffers.
2//!
3//! This crate exports four traits that allow creating iterators over rows or
4//! columns of [`Img`][imgref::Img]s:
5//!
6//! - [`ImgIterPtr`] for `Img<*const [T]>`; allows creating iterators over
7//! `*const` pointers
8//!
9//! - [`ImgIterPtrMut`] for `Img<*mut [T]>`; allows creating iterators over
10//! `*mut` pointers
11//!
12//! - [`ImgIter`] for `Img<&[T]>`; allows creating iterators over shared
13//! references
14//!
15//! - [`ImgIterMut`] for `Img<&mut [T]>`; allows creating iterators over mutable
16//! references
17//!
18//! As well as two utility traits for converting to `Img<*const [T]>` or
19//! `Img<*mut [T]>`:
20//!
21//! - [`ImgAsPtr`] for conversions to `Img<*const [T]>`.
22//!
23//! - [`ImgAsMutPtr`] for conversions to `Img<*mut [T]>`.
24//!
25//! This is actually not implemented by anything other than `Img<*mut [T]>`,
26//! but it exists for the purpose of documenting why it cannot be implemented
27//! for `Img<&mut [T]>`.
28//!
29//! Additionally, when the (experimental!) `simd` feature is enabled, there are
30//! four more traits - [`ImgSimdIter`], [`ImgSimdIterMut`], [`ImgSimdIterPtr`],
31//! and [`ImgSimdIterPtrMut`]. These allow creating iterators over *multiple*
32//! rows or columns of an image at once. They don't actually depend on SIMD or a
33//! nightly compiler - they just return multiple items at once.
34//!
35//! Methods on [`ImgIterPtr`] and [`ImgIterPtrMut`] are `unsafe` because they
36//! offset on the provided pointers. [`ImgIter`] and [`ImgIterMut`] cannot
37//! include safe versions because the pointer iterators may outlive the
38//! references.
39
40pub mod traits;
41pub mod iter;
42
43#[cfg(doc)]
44use traits::*;
45
46// These two utility functions return the length of a slice-ptr, without
47// dereferencing it. This avoids relying on the unstable `slice_ptr_len`
48// feature, but still requires Rust 1.63.0 for `NonNull::len`.
49
50pub(crate) unsafe fn slice_ptr_len<T>(ptr: *const [T]) -> usize {
51 slice_ptr_len_mut(ptr as *mut [T])
52}
53
54pub(crate) unsafe fn slice_ptr_len_mut<T>(ptr: *mut [T]) -> usize {
55 core::ptr::NonNull::new_unchecked(ptr).len()
56}