Struct DataBuf 

pub struct DataBuf<T: ?Sized> { /* private fields */ }

A wrapper acting as an owned buffer for Raylib-allocated memory. Automatically releases the memory with ffi::MemFree() when dropped.

Example

use raylib::prelude::*;
let buf: DataBuf<[u8]> = compress_data(b"11111").unwrap();
// Use this how you used to use the return of `compress_data()`.
// It will live until `buf` goes out of scope or gets dropped.
let data: &[u8] = buf.as_ref();
let expected: &[u8] = &[1, 5, 0, 250, 255, 49, 49, 49, 49, 49];
assert_eq!(data, expected);

Safety

• buf must not be dangling.
• buf must be safe to dereference.
• buf must be a unique, owned pointer (not to static or local memory, and the memory must not be accessible through any pointers/references not derived from the returned DataBuf).
• buf must point to valid, initialized data.
• buf must be convertible to a reference.
• buf must have been created with RL_MALLOC/ffi::MemAlloc or RL_REALLOC/ffi::MemRealloc.

This structure is only intended for use with pointers given by Raylib with the expectation that you would manually deallocate them with ffi::MemFree. DO NOT use this structure to hold arbitrary or un-owned pointers.

If the pointer is expected to be conditionally deallocated by Raylib, (i.e. conditionally passing the buffer to a Raylib function that will certainly deallocatate it) use DataBuf::into_inner to prevent the Drop impl from causing a double-free.

Implementations

impl<T> DataBuf<MaybeUninit<T>>

pub const fn write(self, val: T) -> DataBuf<T>

Initialize the buffer with valid memory.

pub const unsafe fn assume_init(self) -> DataBuf<T>

Mark that the data pointed to by self is initialized.

Safety

The data pointed to by self must actually be initialized.

impl<T> DataBuf<[MaybeUninit<T>]>

pub const unsafe fn assume_init(self) -> DataBuf<[T]>

Mark that the data pointed to by self is initialized.

Safety

The data pointed to by self must actually be initialized.

impl<T: ?Sized> DataBuf<T>

pub const fn as_ref(&self) -> &T

Returns a shared reference to the value.

pub const fn as_mut(&mut self) -> &mut T

Returns a unique reference to the value.

pub const fn into_inner(self) -> RlManaged<T>

Extract the pointer without freeing it, for the purpose of transferring ownership.

WARNING: The returned pointer must be unloaded manually to avoid a memory leak.

impl<T> DataBuf<T>

pub fn alloc() -> Result<DataBuf<MaybeUninit<T>>, AllocationError>

Allocate new memory managed by Raylib.

pub fn alloc_from(val: T) -> Result<Self, (AllocationError, T)>

Allocate new memory managed by Raylib and move val into it.

pub fn alloc_from_clone(src: &T) -> Result<Self, AllocationError>

where T: Clone,

Allocate new memory managed by Raylib and clone val into it.

pub fn alloc_from_copy(src: &T) -> Result<Self, AllocationError>

where T: Copy,

Allocate new memory managed by Raylib and copy val into it.

impl<T> DataBuf<[T]>

pub fn alloc(count: usize) -> Result<DataBuf<[MaybeUninit<T>]>, AllocationError>

Allocate new memory managed by Raylib.

Example

let mut data_buf = DataBuf::<[i32]>::alloc(5).unwrap();
data_buf[0].write(4);
data_buf[1].write(8);
data_buf[2].write(-23);
data_buf[3].write(9);
data_buf[4].write(0);
// SAFETY: Just initialized all elements
let data_buf = unsafe { data_buf.assume_init() };
assert_eq!(data_buf.as_ref(), &[4, 8, -23, 9, 0]);

(See also: DataBuf::alloc_from_copy)

pub fn alloc_from_clone(src: &[T]) -> Result<Self, AllocationError>

where T: Clone,

Allocate memory managed by Raylib and initialize by cloning each element.

If a clone() panics partway through, the already-cloned prefix is dropped and the allocation is freed before the panic propagates — no leak, no drop of uninitialized memory.

Panics

This method may panic in debug if the pointer returned by ffi::MemAlloc is unaligned.

Example

let src = vec![String::from("a"), String::from("b")];
let data_buf = DataBuf::<[String]>::alloc_from_clone(&src).unwrap();
assert_eq!(data_buf.as_ref(), src.as_slice());

pub fn alloc_from_copy(src: &[T]) -> Result<Self, AllocationError>

where T: Copy,

Allocate memory managed by Raylib and initialize by copying.

Panics

This method may panic in debug if the pointer returned by ffi::MemAlloc is unaligned.

Example

let src = [4, 8, -23, 9, 0];
let mut data_buf = DataBuf::<[i32]>::alloc_from_copy(&src).unwrap();
assert_eq!(data_buf.as_ref(), &src);

pub fn realloc( self, new_count: usize, ) -> Result<DataBuf<[MaybeUninit<T>]>, (AllocationError, Self)>

Reallocate memory already managed by Raylib.

Panics

This method may panic in debug if the pointer returned by ffi::MemAlloc is unaligned.

Trait Implementations

impl<T: ?Sized> AsMut<T> for DataBuf<T>

fn as_mut(&mut self) -> &mut T

Converts this type into a mutable reference of the (usually inferred) input type.

impl<T: ?Sized> AsRef<T> for DataBuf<T>

fn as_ref(&self) -> &T

Converts this type into a shared reference of the (usually inferred) input type.

impl<T: Debug + ?Sized> Debug for DataBuf<T>

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

Formats the value using the given formatter.

impl<T: ?Sized> Deref for DataBuf<T>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<T: ?Sized> DerefMut for DataBuf<T>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<T: ?Sized> Drop for DataBuf<T>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

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

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.