Struct PerBuffer 

pub struct PerBuffer<T: 'static>(/* private fields */);

A struct to associate one T to each Buffer

This is very useful to implement the “parser pattern”, where you have one parser per Buffer, acting on changes that take place on each Buffer.

Implementations

impl<T: 'static> PerBuffer<T>

pub const fn new() -> Self

Returns a new mapping of Buffers to a type T

Since this function is const, you can conveniently place it in a static variable, in order to record one T for every Buffer that you want to associate the struct to.

This is very useful in order to create the “parser pattern” on a number of different Buffers, letting you store things and retrieve them as needed.

Note

This function will not automatically add new Buffers to the list. To do that, you should add a hook on Buffer, that calls PerBuffer::register.

Additionally, you will probably also want to setup a hook that calls PerBuffer::unregister on BufferClosed

pub fn register<'p>( &'p self, pa: &'p mut Pass, handle: &'p Handle, new_value: T, ) -> (&'p mut T, &'p mut Buffer)

Register a Buffer with an initial value of T

If there was a previous version of T assoiated with the Buffer, then the new T will replace that old version.

You should most likely call this function on the WidgetOpened<Buffer> hook, often aliased to just Buffer.

pub fn unregister(&self, pa: &mut Pass, handle: &Handle) -> Option<T>

Unregisters a Buffer

This will remove the Buffer from the list, making future calls to Self::write return None. You should consider doing this on the BufferClosed hook. Returns None if the Buffer wasn’t already registered.

pub fn get<'b>(&'b self, buffer_pass: &'b impl BufferPass) -> Option<&'b T>

Gets a reference to the T associated with a Buffer

This function lets you bipass the normal requirement of a Pass in order to acquire a T associated with any given Buffer.

For now, the two types that can be used as [BufferPass]es are the Buffer itself and a Cursor<Buffer>. These types are allowed to do this because they are impossible to acquire without first borrowing from an RwData<Buffer>, either directly or through a Handle

Will return None if the Buffer in question wasn’t registered or was unregistered.

Note: Why is this safe?

From the rest of the operations on this struct, you may glean that the PerBuffer struct is backed by a RwData, and the only way to safely access the data in those is through a Pass.

So why can you suddenly do this without a Pass. Basically, since you can’t construct a Buffer, the only way to actually get one is by borrowing from a RwData<Buffer> or Handle.

Given that, the Pass will already be borrowed, and the Buffer will act as an “extensionto the Pass’s borrow”, and will become invalid at the same time.

It is important to note that this is only safe because Buffers can’t be acquired without a Pass.

pub fn get_mut<'b>( &'b self, buffer: &'b mut impl BufferPass, ) -> Option<&'b mut T>

Gets a mutable reference to the T associated with a Buffer

This function lets you bipass the normal requirement of a Pass in order to acquire a T associated with any given Buffer.

For now, the two types that can be used as [BufferPass]es are the Buffer itself and a Cursor<Buffer>. These types are allowed to do this because they are impossible to acquire without first borrowing from an RwData<Buffer>, either directly or through a Handle

Will return None if the Buffer in question wasn’t registered or was unregistered.

Note: Why is this safe?

For the same reason that PerBuffer::get is safe. However, in order to prevent multiple borrowings from happening at the same time, this will take a mutable borrow of the Buffer, acting much like a &mut Pass in that regard.

pub fn write<'p>( &'p self, pa: &'p mut Pass, handle: &'p Handle, ) -> Option<(&'p mut T, &'p mut Buffer)>

Writes to the Buffer and the T at the same time

Will return None if the Buffer in question wasn’t registered or was unregistered.

pub fn write_with<'p, Tup: WriteableTuple<'p, impl Any>>( &'p self, pa: &'p mut Pass, handle: &'p Handle, tup: Tup, ) -> Option<(&'p mut T, &'p mut Buffer, Tup::Return)>

Writes to the Buffer and a tuple of writeable types

This is an extension to the Pass::write_many method, allowing you to write to many RwData-like structs at once.

Returns None if any two structs, either in the Handle, tuple, or PerBuffer point to the same thing, or if the Buffer wasn’t registered or was unregistered.

pub fn write_many<'p, const N: usize>( &'p self, pa: &'p mut Pass, handles: [&'p Handle; N], ) -> Option<[(&'p mut T, &'p mut Buffer); N]>

Tries to write to a bunch of Buffers and their respective Ts

Returns None if any two Handles point to the same Buffer, or if any of the Buffers weren’t registered or were unregistered.

pub fn write_many_with<'p, const N: usize, Tup: WriteableTuple<'p, impl Any>>( &'p self, pa: &'p mut Pass, handles: [&'p Handle; N], tup: Tup, ) -> Option<([(&'p mut T, &'p mut Buffer); N], Tup::Return)>

Fusion of write_many and write_with

Returns None if any two structs point to the same RwData-like struct, or if any of the Buffers weren’t registered or were unregistered.

Trait Implementations

impl<T: 'static> Default for PerBuffer<T>

fn default() -> Self

Returns the “default value” for a type.