Struct canvas::Rec

pub struct Rec<P: AsBytes + FromBytes> { /* fields omitted */ }

A reinterpretable vector for an array of pixels.

It allows efficient conversion to other pixel representations, that is effective reinterpretation casts.

Methods

impl<P: AsBytes + FromBytes> Rec<P>

pub fn new(count: usize) -> Self where
    P: AsPixel, 

Allocate a pixel buffer by the pixel count.

Panics

This function will panic when the byte-length of the slice with the provided count would exceed the possible usize values. To avoid this, use bytes_for_pixel with manual calculation of the byte length instead.

This function will also panic if the allocation fails.

pub fn new_for_pixel(pixel: Pixel<P>, count: usize) -> Self

Allocate a pixel buffer by the pixel count.

Provides the opportunity to construct the pixel argument via other means than the trait, for example a dynamically checked expression.

Panics

This function will panic when the byte-length of the slice with the provided count would exceed the possible usize values. To avoid this, use bytes_for_pixel with manual calculation of the byte length instead.

This function will also panic if the allocation fails.

pub fn bytes_for_pixel(pixel: Pixel<P>, mem_size: usize) -> Self

Allocate a pixel buffer by providing the byte count you wish to allocate.

Panics

This function will panic if the allocation fails.

pub fn resize(&mut self, count: usize)

Change the number of pixels.

This will always reallocate the buffer if the size exceeds the current capacity.

Panics

This function will panic when the byte-length of the slice with the provided count would exceed the possible usize values. To avoid this, use resize_bytes with manual calculation of the byte length instead.

This function will also panic if an allocation is necessary but fails.

pub fn resize_bytes(&mut self, bytes: usize)

Change the size in bytes.

The length is afterwards equal to bytes / mem::size_of::<P>(), i.e. the quotient rounded down.

This will always reallocate the buffer if the size exceeds the current capacity.

Panics

This function will panic if an allocation is necessary but fails.

pub fn reuse(&mut self, count: usize) -> Result<(), ReuseError>

Change the number of pixels without reallocation.

Returns Ok when the resizing was successfully completed to the requested size and returns Err if this could not have been performed without a reallocation. This function will also never deallocate memory.

// Initial allocation may panic due to allocation error for now.
let mut buffer: Rec<u16> = Rec::new(100);
buffer.reuse(0)
    .expect("Requested size smaller than allocation");
buffer.reuse(100)
    .expect("The buffer didn't shrink from previous reuse");

// Capacity may be larger than requested size at initialization.
let capacity = buffer.capacity();
buffer.reuse(capacity)
    .expect("Set to full underlying allocation size.");

pub fn reuse_bytes(&mut self, bytes: usize) -> Result<(), ReuseError>

Change the number of bytes without reallocation.

Returns Ok when the resizing was successfully completed to the requested size and returns Err with the new byte size otherwise.

pub fn shrink_to_fit(&mut self)

Reallocate the slice to contain exactly as many bytes as necessary.

The number of contained elements is not changed. However, the number of elements interpreted as a different type may change.

let rec_u8 = Rec::<u8>::new(7);
assert_eq!(rec_u8.len(), 7);

let mut rec_u32 = rec_u8.reinterpret::<u32>();
assert_eq!(rec_u32.len(), 1);
rec_u32.shrink_to_fit();

let rec_u8 = rec_u32.reinterpret::<u8>();
assert_eq!(rec_u8.len(), 4);

Panics

This function will panic if the allocation fails.

pub fn as_slice(&self) -> &[P]

pub fn as_mut_slice(&mut self) -> &mut [P]

pub fn len(&self) -> usize

The number of accessible elements for the current type.

pub fn capacity(&self) -> usize

The number of elements that can fit without reallocation.

pub fn as_bytes(&self) -> &[u8]

pub fn as_bytes_mut(&mut self) -> &mut [u8]

pub fn byte_len(&self) -> usize

The total number of managed bytes.

This will not change even through a reinterpretation casts. This corresponds to the capacity of the storage.

pub fn byte_capacity(&self) -> usize

The total number of managable bytes.

pub fn reinterpret<Q>(self) -> Rec<Q> where
    Q: AsPixel + AsBytes + FromBytes, 

Reinterpret the buffer for a different type of pixel.

See reinterpret_to for details.

pub fn reinterpret_to<Q>(self, pixel: Pixel<Q>) -> Rec<Q> where
    Q: AsBytes + FromBytes, 

Reinterpret the buffer for a different type of pixel.

Note that this may leave some of the underlying pixels unaccessible if the new type is larger than the old one and the allocation was not a multiple of the new size. Conversely, some new bytes may become accessible if the memory length was not a multiple of the previous pixel type's length.

Trait Implementations

impl<P: AsBytes + FromBytes + Eq> Eq for Rec<P>

impl<P: AsBytes + FromBytes + Ord> Ord for Rec<P>

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

🔬 This is a nightly-only experimental API. (clamp)

Restrict a value to a certain interval.

impl<P: AsBytes + FromBytes + PartialEq> PartialEq<Rec<P>> for Rec<P>

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

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

This method tests for !=.

impl<P: AsBytes + FromBytes> Clone for Rec<P>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<P: AsBytes + FromBytes + PartialOrd> PartialOrd<Rec<P>> for Rec<P>

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

#[must_use]

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

This method tests less than (for self and other) and is used by the < operator.

#[must_use]

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

This method tests less than or equal to (for self and other) and is used by the <= operator.

#[must_use]

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

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]

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

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<P: AsBytes + FromBytes + AsPixel> Default for Rec<P>

fn default() -> Self

Returns the "default value" for a type.

impl<P: AsBytes + FromBytes> DerefMut for Rec<P>

fn deref_mut(&mut self) -> &mut [P]

Mutably dereferences the value.

impl<P: AsBytes + FromBytes> Deref for Rec<P>

type Target = [P]

The resulting type after dereferencing.

fn deref(&self) -> &[P]

Dereferences the value.

impl<P: AsBytes + FromBytes + Debug> Debug for Rec<P>

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

Formats the value using the given formatter.