Libwaysip

https://docs.rs/libwaysip/0.7.0/libwaysip/
Admin
Libwaysip is a Rust library for interactive screen, area, and point selection under Wayland...
Tokens:8,913
Snippets:101
Trust Score:9.1
Update:1 month ago
Show doc for...
Tokens:
Raw
### Construct Box from raw pointer

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Examples demonstrating how to recreate a Box from a raw pointer or manually allocate memory for a Box using the system allocator.

```rust
#![feature(allocator_api)]

use std::alloc::System;

let x = Box::new_in(5, System);
let (ptr, alloc) = Box::into_raw_with_allocator(x);
let x = unsafe { Box::from_raw_in(ptr, alloc) };
```

```rust
#![feature(allocator_api, slice_ptr_get)]

use std::alloc::{Allocator, Layout, System};

unsafe {
    let ptr = System.allocate(Layout::new::<i32>())?.as_mut_ptr() as *mut i32;
    // In general .write is required to avoid attempting to destruct
    // the (uninitialized) previous contents of `ptr`, though for this
    // simple example `*ptr = 5` would have worked as well.
    ptr.write(5);
    let x = Box::from_raw_in(ptr, System);
}
```

--------------------------------

### Construct Box from NonNull pointer

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Examples demonstrating how to recreate a Box from a NonNull pointer or manually allocate memory for a Box using the system allocator.

```rust
#![feature(allocator_api)]

use std::alloc::System;

let x = Box::new_in(5, System);
let (non_null, alloc) = Box::into_non_null_with_allocator(x);
let x = unsafe { Box::from_non_null_in(non_null, alloc) };
```

```rust
#![feature(allocator_api)]

use std::alloc::{Allocator, Layout, System};

unsafe {
    let non_null = System.allocate(Layout::new::<i32>())?.cast::<i32>();
    // In general .write is required to avoid attempting to destruct
    // the (uninitialized) previous contents of `non_null`.
    non_null.write(5);
    let x = Box::from_non_null_in(non_null, System);
}
```

--------------------------------

### Consume Box into raw pointer and allocator

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Demonstrates consuming a Box into a raw pointer and allocator, with examples for automatic and manual memory cleanup.

```rust
#![feature(allocator_api)]

use std::alloc::System;

let x = Box::new_in(String::from("Hello"), System);
let (ptr, alloc) = Box::into_raw_with_allocator(x);
let x = unsafe { Box::from_raw_in(ptr, alloc) };
```

```rust
#![feature(allocator_api)]

use std::alloc::{Allocator, Layout, System};
use std::ptr::{self, NonNull};

let x = Box::new_in(String::from("Hello"), System);
let (ptr, alloc) = Box::into_raw_with_allocator(x);
unsafe {
    ptr::drop_in_place(ptr);
    let non_null = NonNull::new_unchecked(ptr);
    alloc.deallocate(non_null.cast(), Layout::new::<String>());
}
```

--------------------------------

### Consume Box into NonNull pointer and allocator

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Demonstrates consuming a Box into a NonNull pointer and allocator, with examples for automatic and manual memory cleanup.

```rust
#![feature(allocator_api)]

use std::alloc::System;

let x = Box::new_in(String::from("Hello"), System);
let (non_null, alloc) = Box::into_non_null_with_allocator(x);
let x = unsafe { Box::from_non_null_in(non_null, alloc) };
```

```rust
#![feature(allocator_api)]

use std::alloc::{Allocator, Layout, System};

let x = Box::new_in(String::from("Hello"), System);
let (non_null, alloc) = Box::into_non_null_with_allocator(x);
unsafe {
    non_null.drop_in_place();
    alloc.deallocate(non_null.cast::<u8>(), Layout::new::<String>());
}
```

--------------------------------

### Leaking Box memory

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Examples of consuming a Box to return a static mutable reference for both sized and unsized data.

```rust
let x = Box::new(41);
let static_ref: &'static mut usize = Box::leak(x);
*static_ref += 1;
assert_eq!(*static_ref, 42);
```

```rust
let x = vec![1, 2, 3].into_boxed_slice();
let static_ref = Box::leak(x);
static_ref[0] = 4;
assert_eq!(*static_ref, [4, 2, 3]);
```

--------------------------------

### BoxInfo Struct Definition

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/state/struct.BoxInfo.html

The structure definition for BoxInfo, containing the start and end coordinates of a box.

```rust
pub struct BoxInfo {
    pub start_x: f64,
    pub start_y: f64,
    pub end_x: f64,
    pub end_y: f64,
}
```

--------------------------------

### WlOutputInfo::new

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/state/struct.WlOutputInfo.html

Creates a new instance of WlOutputInfo for the given output.

```APIDOC
## pub fn new(output: WlOutput) -> Self

### Description
Creates a new WlOutputInfo instance associated with the provided WlOutput.

### Parameters
- **output** (WlOutput) - Required - The Wayland output object.
```

--------------------------------

### ZXdgOutputInfo::new

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/state/struct.ZXdgOutputInfo.html

Creates a new instance of ZXdgOutputInfo from a ZxdgOutputV1 object.

```APIDOC
## pub fn new(zxdgoutput: ZxdgOutputV1) -> Self

### Description
Creates a new instance of the `ZXdgOutputInfo` struct using the provided `ZxdgOutputV1` object.

### Parameters
- **zxdgoutput** (ZxdgOutputV1) - Required - The XDG output object to initialize the info with.

### Returns
- **Self** - A new instance of `ZXdgOutputInfo`.
```

--------------------------------

### WlOutputInfo::get_description

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/state/struct.WlOutputInfo.html

Retrieves the description of the output.

```APIDOC
## pub fn get_description(&self) -> &str

### Description
Returns the description of the output as a string slice.
```

--------------------------------

### Box::new_uninit_in

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Constructs a new box with uninitialized contents in the provided allocator.

```APIDOC
## pub fn new_uninit_in(alloc: A) -> Box<MaybeUninit<T>, A>

### Description
Constructs a new box with uninitialized contents in the provided allocator.
```

--------------------------------

### WaySip::get

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/struct.WaySip.html

Executes the selection process and returns the result.

```APIDOC
## pub fn get(self) -> Result<Option<AreaInfo>, WaySipError>

### Description
Executes the area selection process based on the configured parameters and returns the selected area information.

### Returns
- `Result<Option<AreaInfo>, WaySipError>`: Returns the selected area if successful, or an error if the selection failed.
```

--------------------------------

### WlOutputInfo::get_output

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/state/struct.WlOutputInfo.html

Retrieves the underlying WlOutput object.

```APIDOC
## pub fn get_output(&self) -> &WlOutput

### Description
Returns a reference to the underlying WlOutput object.
```

--------------------------------

### Manually allocate Box from global allocator

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Shows how to manually allocate memory using the global allocator and wrap it in a Box.

```rust
use std::alloc::{alloc, Layout};

unsafe {
    let ptr = alloc(Layout::new::<i32>()) as *mut i32;
    // In general .write is required to avoid attempting to destruct
    // the (uninitialized) previous contents of `ptr`, though for this
    // simple example `*ptr = 5` would have worked as well.
    ptr.write(5);
    let x = Box::from_raw(ptr);
}
```

--------------------------------

### pub fn into_pin(boxed: Box<T, A>) -> Pin<Box<T, A>>

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Converts a Box<T> into a Pin<Box<T>>.

```APIDOC
## pub fn into_pin(boxed: Box<T, A>) -> Pin<Box<T, A>>

### Description
Converts a `Box<T>` into a `Pin<Box<T>>`. If `T` does not implement `Unpin`, then `*boxed` will be pinned in memory and unable to be moved.
```

--------------------------------

### WlOutputInfo::get_screen_info

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/state/struct.WlOutputInfo.html

Retrieves the screen information associated with this output.

```APIDOC
## pub fn get_screen_info(&self) -> ScreenInfo

### Description
Returns the ScreenInfo structure containing details about the output's screen configuration.
```

--------------------------------

### Manually allocate Box from NonNull pointer

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Shows how to manually allocate memory and wrap it in a Box using a NonNull pointer.

```rust
use std::alloc::{alloc, Layout};
use std::ptr::NonNull;

unsafe {
    let non_null = NonNull::new(alloc(Layout::new::<i32>()).cast::<i32>())
        .expect("alloc should have successfully allocated memory");
    // In general .write is required to avoid attempting to destruct
    // the (uninitialized) previous contents of `non_null`.
    non_null.write(5);
    let x = Box::from_non_null(non_null);
}
```

--------------------------------

### Convert Box to raw pointer

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Demonstrates consuming a Box into a raw pointer and various ways to handle memory cleanup.

```rust
let x = Box::new(String::from("Hello"));
let ptr = Box::into_raw(x);
let x = unsafe { Box::from_raw(ptr) };
```

```rust
use std::alloc::{dealloc, Layout};
use std::ptr;

let x = Box::new(String::from("Hello"));
let ptr = Box::into_raw(x);
unsafe {
    ptr::drop_in_place(ptr);
    dealloc(ptr as *mut u8, Layout::new::<String>());
}
```

```rust
let x = Box::new(String::from("Hello"));
let ptr = Box::into_raw(x);
unsafe {
    drop(Box::from_raw(ptr));
}
```

--------------------------------

### WlOutputInfo::get_size

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/state/struct.WlOutputInfo.html

Retrieves the size of the output.

```APIDOC
## pub fn get_size(&self) -> Size

### Description
Returns the dimensions of the output as a Size object.
```

--------------------------------

### WlOutputInfo::get_name

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/state/struct.WlOutputInfo.html

Retrieves the name of the output.

```APIDOC
## pub fn get_name(&self) -> &str

### Description
Returns the name of the output as a string slice.
```

--------------------------------

### Allocate memory with Box::new

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Allocates memory on the heap and places the value into it.

```rust
let five = Box::new(5);
```

--------------------------------

### Avoid ambiguous From implementations

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Demonstrates why implementing From for Pin is discouraged as it creates ambiguity with Pin::from.

```rust
struct Foo; // A type defined in this crate.
impl From<Box<()>> for Pin<Foo> {
    fn from(_: Box<()>) -> Pin<Foo> {
        Pin::new(Foo)
    }
}

let foo = Box::new(());
let bar = Pin::from(foo);
```

--------------------------------

### Box::try_clone_from_ref_in

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Allocates memory in the given allocator then clones src into it, returning an error if allocation fails.

```APIDOC
## pub fn try_clone_from_ref_in(src: &T, alloc: A) -> Result<Box<T, A>, AllocError>

### Description
Allocates memory in the given allocator then clones `src` into it, returning an error if allocation fails. This doesn’t actually allocate if `src` is zero-sized.
```

--------------------------------

### pub fn as_non_null(b: &mut Box<T, A>) -> NonNull<T>

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Returns a NonNull pointer to the Box's contents. This is a nightly-only experimental API.

```APIDOC
## pub fn as_non_null(b: &mut Box<T, A>) -> NonNull<T>

### Description
Returns a `NonNull` pointer to the `Box`’s contents. This is a nightly-only experimental API (`box_as_non_null`).
```

--------------------------------

### Box::clone_from_ref_in

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Allocates memory in the given allocator then clones src into it.

```APIDOC
## pub fn clone_from_ref_in(src: &T, alloc: A) -> Box<T, A>

### Description
Allocates memory in the given allocator then clones `src` into it. This doesn’t actually allocate if `src` is zero-sized.
```

--------------------------------

### Clone from reference to Box

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Requires the clone_from_ref feature. Allocates memory and clones the source into the new box.

```rust
#![feature(clone_from_ref)]

let hello: Box<str> = Box::clone_from_ref("hello");
```

--------------------------------

### Define BackgroundProvider type alias

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Defines the callback signature for providing a static backdrop image for a given output.

```rust
pub type BackgroundProvider = Box<dyn Fn(&WlOutput, &str) -> Option<ImageSurface>>;
```

--------------------------------

### pub fn allocator(b: &Box<T, A>) -> &A

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Returns a reference to the underlying allocator. This is a nightly-only experimental API.

```APIDOC
## pub fn allocator(b: &Box<T, A>) -> &A

### Description
Returns a reference to the underlying allocator. This is a nightly-only experimental API (`allocator_api`). Note: this is an associated function, which means that you have to call it as `Box::allocator(&b)` instead of `b.allocator()`.
```

--------------------------------

### Box::pin_in

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Constructs a new Pin<Box<T, A>>.

```APIDOC
## pub fn pin_in(x: T, alloc: A) -> Pin<Box<T, A>>

### Description
Constructs a new Pin<Box<T, A>>. If T does not implement Unpin, then x will be pinned in memory.
```

--------------------------------

### WlOutputInfo Struct Definition

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/state/struct.WlOutputInfo.html

The structure definition for WlOutputInfo, containing fields for output metadata and state.

```rust
pub struct WlOutputInfo {
    pub output: WlOutput,
    pub description: String,
    pub name: String,
    pub size: Size,
    pub xdg_output_info: OnceCell<ZXdgOutputInfo>,
}
```

--------------------------------

### Reconstruct Box from raw pointer

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Demonstrates recreating a Box from a raw pointer previously obtained via Box::into_raw.

```rust
let x = Box::new(5);
let ptr = Box::into_raw(x);
let x = unsafe { Box::from_raw(ptr) };
```

--------------------------------

### Box::from_raw_in

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Constructs a box from a raw pointer in the given allocator. The Box takes ownership of the pointer and will manage its memory and destruction.

```APIDOC
## pub unsafe fn from_raw_in(raw: *mut T, alloc: A) -> Box<T, A>

### Description
Constructs a box from a raw pointer in the given allocator. After calling this function, the raw pointer is owned by the resulting Box, which will handle the destructor of T and free the memory.

### Safety
This function is unsafe. Improper use may lead to memory problems such as double-frees. The raw pointer must point to a block of memory allocated by the provided allocator.
```

--------------------------------

### Box::take

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Consumes the Box without consuming its allocation, returning the wrapped value and a Box to the uninitialized memory.

```APIDOC
## pub fn take(boxed: Box<T, A>) -> (T, Box<MaybeUninit<T>, A>)

### Description
Consumes the `Box` without consuming its allocation, returning the wrapped value and a `Box` to the uninitialized memory where the wrapped value used to live. This can be used together with `write` to reuse the allocation for multiple boxed values.
```

--------------------------------

### WaySip Builder Methods

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/struct.WaySip.html

The WaySip struct uses a builder pattern to configure selection parameters before executing the selection process.

```APIDOC
## WaySip Builder Methods

### Description
Configure the behavior and appearance of the area selection tool using these builder methods.

### Methods
- `new()`: Creates a new WaySip instance.
- `with_connection(conn: Connection)`: Sets the Wayland connection.
- `with_selection_type(selection_type: SelectionType)`: Sets the type of selection.
- `with_background_color(color: Color)`: Sets the background color.
- `with_foreground_color(color: Color)`: Sets the foreground color.
- `with_border_text_color(color: Color)`: Sets the border text color.
- `with_box_color(color: Color)`: Sets the box color.
- `with_border_weight(border_weight: f64)`: Sets the border weight.
- `with_font_size(font_size: i32)`: Sets the font size.
- `with_font_name(font_name: String)`: Sets the font name.
- `with_predefined_boxes(boxes: Vec<BoxInfo>)`: Sets predefined selection boxes.
- `with_aspect_ratio(width: f64, height: f64)`: Sets the aspect ratio.
- `with_edit_selection()`: Enables editing the selection before confirmation.
- `with_confirm_key(key: u32)`: Sets the keycode used to confirm the selection.
- `with_background_provider<F>(provider: F)`: Sets a custom background image provider.
```

--------------------------------

### Construct uninitialized Box

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Creates a new box with uninitialized contents, requiring manual initialization before use.

```rust
let mut five = Box::<u32>::new_uninit();
// Deferred initialization:
five.write(5);
let five = unsafe { five.assume_init() };

assert_eq!(*five, 5)
```

--------------------------------

### Clone from reference in allocator

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Allocates memory in the given allocator and clones the source into it. Requires the clone_from_ref and allocator_api features.

```rust
#![feature(clone_from_ref)]
#![feature(allocator_api)]

use std::alloc::System;

let hello: Box<str, System> = Box::clone_from_ref_in("hello", System);
```

```rust
#![feature(clone_from_ref)]
#![feature(allocator_api)]

use std::alloc::System;

let hello: Box<str, System> = Box::try_clone_from_ref_in("hello", System)?;
```

--------------------------------

### Fallible clone from reference

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Requires the clone_from_ref and allocator_api features. Clones the source into a new box with error handling.

```rust
#![feature(clone_from_ref)]
#![feature(allocator_api)]

let hello: Box<str> = Box::try_clone_from_ref("hello")?;
```

--------------------------------

### Convert Box to NonNull pointer

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Demonstrates consuming a Box into a NonNull pointer and various ways to handle memory cleanup.

```rust
let x = Box::new(String::from("Hello"));
let non_null = Box::into_non_null(x);
let x = unsafe { Box::from_non_null(non_null) };
```

```rust
use std::alloc::{dealloc, Layout};

let x = Box::new(String::from("Hello"));
let non_null = Box::into_non_null(x);
unsafe {
    non_null.drop_in_place();
    dealloc(non_null.as_ptr().cast::<u8>(), Layout::new::<String>());
}
```

```rust
let x = Box::new(String::from("Hello"));
let non_null = Box::into_non_null(x);
unsafe {
    drop(Box::from_non_null(non_null));
}
```

--------------------------------

### Convert T to Box<T>

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Demonstrates the conversion of a value into a heap-allocated Box.

```rust
let x = 5;
let boxed = Box::new(5);

assert_eq!(Box::from(x), boxed);
```

--------------------------------

### Allocate with custom allocator

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Allocates memory using a specific allocator and places a value into it.

```rust
#![feature(allocator_api)]

use std::alloc::System;

let five = Box::new_in(5, System);
```

```rust
#![feature(allocator_api)]

use std::alloc::System;

let five = Box::try_new_in(5, System)?;
```

--------------------------------

### Box::new_in

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Allocates memory in the given allocator and places the value into it.

```APIDOC
## pub fn new_in(x: T, alloc: A) -> Box<T, A>

### Description
Allocates memory in the given allocator then places `x` into it. This does not allocate if `T` is zero-sized.

### Parameters
- **x** (T) - The value to place in the box.
- **alloc** (A) - The allocator to use for memory allocation.
```

--------------------------------

### Box::into_raw_with_allocator

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Consumes the Box, returning a wrapped raw pointer and the allocator. The caller is responsible for the memory previously managed by the Box.

```APIDOC
## Box::into_raw_with_allocator(b: Box<T, A>) -> (*mut T, A)

### Description
Consumes the Box, returning a wrapped raw pointer and the allocator. The pointer will be properly aligned and non-null. After calling this function, the caller is responsible for the memory previously managed by the Box.

### Parameters
- **b** (Box<T, A>) - Required - The Box to consume.
```

--------------------------------

### Accessing Box contents via raw pointers

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Demonstrates the aliasing guarantees when using as_ptr and as_mut_ptr to access Box contents.

```rust
unsafe {
    let mut v = Box::new(0);
    let ptr1 = Box::as_ptr(&v);
    let ptr2 = Box::as_mut_ptr(&mut v);
    let _val = ptr2.read();
    // No write to this memory has happened yet, so `ptr1` is still valid.
    let _val = ptr1.read();
    // However, once we do a write...
    ptr2.write(1);
    // ... `ptr1` is no longer valid.
    // This would be UB: let _val = ptr1.read();
}
```

--------------------------------

### Allocate uninitialized memory

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Constructs a box with uninitialized contents using a custom allocator.

```rust
#![feature(allocator_api)]

use std::alloc::System;

let mut five = Box::<u32, _>::new_uninit_in(System);
// Deferred initialization:
five.write(5);
let five = unsafe { five.assume_init() };

assert_eq!(*five, 5)
```

```rust
#![feature(allocator_api)]

use std::alloc::System;

let mut five = Box::<u32, _>::try_new_uninit_in(System)?;
// Deferred initialization:
five.write(5);
let five = unsafe { five.assume_init() };

assert_eq!(*five, 5);
```

--------------------------------

### Box::new_zeroed_in

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Constructs a new box with memory filled with 0 bytes in the provided allocator.

```APIDOC
## pub fn new_zeroed_in(alloc: A) -> Box<MaybeUninit<T>, A>

### Description
Constructs a new Box with uninitialized contents, with the memory being filled with 0 bytes in the provided allocator.
```

--------------------------------

### Box::from_non_null_in

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Constructs a box from a NonNull pointer in the given allocator. The Box takes ownership of the pointer and will manage its memory and destruction.

```APIDOC
## pub unsafe fn from_non_null_in(raw: NonNull<T>, alloc: A) -> Box<T, A>

### Description
Constructs a box from a NonNull pointer in the given allocator. After calling this function, the NonNull pointer is owned by the resulting Box, which will handle the destructor of T and free the memory.

### Safety
This function is unsafe. Improper use may lead to memory problems such as double-frees. The non-null pointer must point to a block of memory allocated by the provided allocator.
```

--------------------------------

### Box::try_new_in

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Allocates memory in the given allocator and places the value into it, returning an error if allocation fails.

```APIDOC
## pub fn try_new_in(x: T, alloc: A) -> Result<Box<T, A>, AllocError>

### Description
Allocates memory in the given allocator then places `x` into it, returning an error if the allocation fails.
```

--------------------------------

### Reconstruct Box from NonNull pointer

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Demonstrates recreating a Box from a NonNull pointer previously obtained via Box::into_non_null.

```rust
let x = Box::new(5);
let non_null = Box::into_non_null(x);
let x = unsafe { Box::from_non_null(non_null) };
```

--------------------------------

### Construct zeroed Box

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Creates a new box with memory initialized to zero bytes.

```rust
let zero = Box::<u32>::new_zeroed();
let zero = unsafe { zero.assume_init() };

assert_eq!(*zero, 0)
```

--------------------------------

### Allocate zeroed memory

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Constructs a box with memory initialized to zero bytes using a custom allocator.

```rust
#![feature(allocator_api)]

use std::alloc::System;

let zero = Box::<u32, _>::new_zeroed_in(System);
let zero = unsafe { zero.assume_init() };

assert_eq!(*zero, 0)
```

```rust
#![feature(allocator_api)]

use std::alloc::System;

let zero = Box::<u32, _>::try_new_zeroed_in(System)?;
let zero = unsafe { zero.assume_init() };

assert_eq!(*zero, 0);
```

--------------------------------

### Clone a Box

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Creates a new box with a clone of the original box's contents.

```rust
let x = Box::new(5);
let y = x.clone();

// The value is the same
assert_eq!(x, y);

// But they are unique objects
assert_ne!(&*x as *const i32, &*y as *const i32);
```

--------------------------------

### Pin a value in a custom allocator

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Constructs a pinned box using a custom allocator.

```rust
#![feature(allocator_api)]
use std::alloc::System;

let x = Box::pin_in(1, System);
```

--------------------------------

### Accessing Box contents via NonNull

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Requires the box_as_non_null feature gate. Shows how multiple NonNull pointers can coexist without invalidating each other.

```rust
#![feature(box_as_non_null)]

unsafe {
    let mut b = Box::new(0);
    let ptr1 = Box::as_non_null(&mut b);
    ptr1.write(1);
    let ptr2 = Box::as_non_null(&mut b);
    ptr2.write(2);
    // Notably, the write to `ptr2` did *not* invalidate `ptr1`:
    ptr1.write(3);
}
```

--------------------------------

### pub fn as_ptr(b: &Box<T, A>) -> *const T

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Returns a raw pointer to the Box's contents. The caller must ensure the Box outlives the pointer and that the memory is not written to using this pointer.

```APIDOC
## pub fn as_ptr(b: &Box<T, A>) -> *const T

### Description
Returns a raw pointer to the `Box`’s contents. The caller must ensure that the `Box` outlives the pointer this function returns, or else it will end up dangling.
```

--------------------------------

### Box::into_non_null_with_allocator

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Consumes the Box, returning a wrapped NonNull pointer and the allocator. The caller is responsible for the memory previously managed by the Box.

```APIDOC
## Box::into_non_null_with_allocator(b: Box<T, A>) -> (NonNull<T>, A)

### Description
Consumes the Box, returning a wrapped NonNull pointer and the allocator. The pointer will be properly aligned. After calling this function, the caller is responsible for the memory previously managed by the Box.

### Parameters
- **b** (Box<T, A>) - Required - The Box to consume.
```

--------------------------------

### Access Box as mutable pointer

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Demonstrates the aliasing guarantee when using as_mut_ptr to perform multiple writes.

```rust
unsafe {
    let mut b = Box::new(0);
    let ptr1 = Box::as_mut_ptr(&mut b);
    ptr1.write(1);
    let ptr2 = Box::as_mut_ptr(&mut b);
    ptr2.write(2);
    // Notably, the write to `ptr2` did *not* invalidate `ptr1`:
    ptr1.write(3);
}
```

--------------------------------

### ScreenInfo Struct Definition

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/state/struct.ScreenInfo.html

The definition of the ScreenInfo struct, containing fields for position, screen size, output size, and associated Wayland output data.

```rust
pub struct ScreenInfo {
    pub position: Position,
    pub screen_size: Size,
    pub wl_output: WlOutput,
    pub output_size: Size,
    pub name: String,
    pub description: String,
}
```

--------------------------------

### Try map value in a Box

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Requires the smart_pointer_try_map feature. Attempts to map the inner value and returns a result.

```rust
#![feature(smart_pointer_try_map)]

let b = Box::new(7);
let new = Box::try_map(b, u32::try_from).unwrap();
assert_eq!(*new, 7);
```

--------------------------------

### Style Struct Definition

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/struct.Style.html

The primary data structure defining the visual style, containing color, border, and font properties.

```rust
pub struct Style {
    pub background_color: Color,
    pub foreground_color: Color,
    pub border_text_color: Color,
    pub box_color: Color,
    pub border_weight: f64,
    pub font_size: i32,
    pub font_name: String,
}
```

--------------------------------

### Fallible uninitialized Box allocation

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Requires the allocator_api feature. Constructs an uninitialized box on the heap with error handling.

```rust
#![feature(allocator_api)]

let mut five = Box::<u32>::try_new_uninit()?;
// Deferred initialization:
five.write(5);
let five = unsafe { five.assume_init() };

assert_eq!(*five, 5);
```

--------------------------------

### get_box_from_str

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/state/struct.BoxInfo.html

Parses a string representation into a BoxInfo instance.

```APIDOC
## pub fn get_box_from_str(box_string: &str) -> Result<Self, BoxInfoError>

### Description
Parses a string input to construct a new BoxInfo instance containing the defined coordinates.

### Parameters
- **box_string** (&str) - Required - The string representation of the box coordinates.

### Returns
- **Result<Self, BoxInfoError>** - Returns a new BoxInfo instance on success, or a BoxInfoError if parsing fails.
```

--------------------------------

### Box::into_raw

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Consumes the Box and returns a raw pointer to the contained value. The caller assumes responsibility for memory cleanup.

```APIDOC
## pub fn into_raw(b: Box<T>) -> *mut T

### Description
Consumes the `Box`, returning a wrapped raw pointer. The pointer will be properly aligned and non-null. After calling this function, the caller is responsible for the memory previously managed by the `Box`.

### Parameters
- **b** (Box<T>) - Required - The Box to consume.
```

--------------------------------

### ZXdgOutputInfo Struct Definition

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/state/struct.ZXdgOutputInfo.html

The primary structure definition containing the XDG output protocol object and its associated metadata.

```rust
pub struct ZXdgOutputInfo {
    pub zxdg_output: ZxdgOutputV1,
    pub size: Size,
    pub start_position: Position,
    pub name: String,
    pub description: String,
}
```

--------------------------------

### Map value in a Box

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Requires the smart_pointer_try_map feature. Reuses the existing allocation to map the inner value.

```rust
#![feature(smart_pointer_try_map)]

let b = Box::new(7);
let new = Box::map(b, |i| i + 7);
assert_eq!(*new, 14);
```

--------------------------------

### Clone contents into an existing Box

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Copies the contents of the source box into the current box without performing a new allocation.

```rust
let x = Box::new(5);
let mut y = Box::new(10);
let yp: *const i32 = &*y;

y.clone_from(&x);

// The value is the same
assert_eq!(x, y);

// And no allocation occurred
assert_eq!(yp, &*y);
```

--------------------------------

### Fallible heap allocation with try_new

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Requires the allocator_api feature. Returns an error if the heap allocation fails.

```rust
#![feature(allocator_api)]

let five = Box::try_new(5)?;
```

--------------------------------

### Color Struct Definition

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/struct.Color.html

The primary structure used to define color properties in libwaysip.

```rust
pub struct Color {
    pub r: f64,
    pub g: f64,
    pub b: f64,
    pub a: f64,
}
```

--------------------------------

### AreaInfo Struct Definition

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/state/struct.AreaInfo.html

The primary structure definition for AreaInfo containing box, screen, and selection information.

```rust
pub struct AreaInfo {
    pub box_info: BoxInfo,
    pub screen_info: ScreenInfo,
    pub effective_selection_type: Option<SelectionType>,
}
```

--------------------------------

### Box::as_mut_ptr

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Returns a raw mutable pointer to the Box’s contents.

```APIDOC
## Box::as_mut_ptr(b: &mut Box<T, A>) -> *mut T

### Description
Returns a raw mutable pointer to the Box’s contents. The caller must ensure that the Box outlives the pointer this function returns.

### Parameters
- **b** (&mut Box<T, A>) - Required - A mutable reference to the Box.
```

--------------------------------

### Fallible zeroed Box allocation

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Requires the allocator_api feature. Constructs a zeroed box on the heap with error handling.

```rust
#![feature(allocator_api)]

let zero = Box::<u32>::try_new_zeroed()?;
let zero = unsafe { zero.assume_init() };

assert_eq!(*zero, 0);
```

--------------------------------

### Box::into_inner

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Consumes the Box and returns the wrapped value.

```APIDOC
## pub fn into_inner(boxed: Box<T, A>) -> T

### Description
Consumes the Box, returning the wrapped value.
```

--------------------------------

### Position Struct Definition

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/struct.Position.html

The core structure definition for representing a point with generic coordinates.

```rust
pub struct Position<T = i32> {
    pub x: T,
    pub y: T,
}
```

--------------------------------

### pub fn leak<'a>(b: Box<T, A>) -> &'a mut T

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Consumes and leaks the Box, returning a mutable reference.

```APIDOC
## pub fn leak<'a>(b: Box<T, A>) -> &'a mut T

### Description
Consumes and leaks the `Box`, returning a mutable reference, `&'a mut T`. Note that the type `T` must outlive the chosen lifetime `'a`.
```

--------------------------------

### Box::into_non_null

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Consumes the Box and returns a NonNull pointer to the contained value. The caller assumes responsibility for memory cleanup.

```APIDOC
## pub fn into_non_null(b: Box<T>) -> NonNull<T>

### Description
Consumes the `Box`, returning a wrapped `NonNull` pointer. The pointer will be properly aligned. After calling this function, the caller is responsible for the memory previously managed by the `Box`.

### Parameters
- **b** (Box<T>) - Required - The Box to consume.
```

--------------------------------

### Take value from Box

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Consumes the Box without consuming its allocation, returning the wrapped value and a Box to the uninitialized memory.

```rust
assert_eq!(Box::into_inner(c), 5);
```

```rust
#![feature(box_take)]

let c = Box::new(5);

// take the value out of the box
let (value, uninit) = Box::take(c);
assert_eq!(value, 5);

// reuse the box for a second value
let c = Box::write(uninit, 6);
assert_eq!(*c, 6);
```

--------------------------------

### Consume a box

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/type.BackgroundProvider.html

Consumes the box and returns the inner value.

```rust
#![feature(box_into_inner)]

let c = Box::new(5);
```

--------------------------------

### hex_to_color

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/struct.Color.html

Converts a hexadecimal color string into a Color struct instance.

```APIDOC
## pub fn hex_to_color(colorhex: String) -> Result<Color, ColorError>

### Description
Converts a hexadecimal color string (e.g., "#RRGGBB") into a `Color` struct. Returns a `Result` containing the `Color` on success or a `ColorError` if the input string is invalid.

### Parameters
- **colorhex** (String) - Required - The hexadecimal color string to convert.

### Returns
- **Result<Color, ColorError>** - The resulting color object or an error.
```

--------------------------------

### Size Struct Definition

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/struct.Size.html

The primary definition of the Size struct, which is generic over type T with a default of i32.

```rust
pub struct Size<T = i32> {
    pub width: T,
    pub height: T,
}
```

--------------------------------

### SelectionType Enum Definition

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/state/enum.SelectionType.html

The definition of the SelectionType enum, representing the available selection modes.

```rust
pub enum SelectionType {
    Area,
    Point,
    Screen,
    PredefinedBoxes,
    DimensionsOrOutput,
}
```

--------------------------------

### WaySipError Enum Definition

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/error/enum.WaySipError.html

The structure of the WaySipError enum, representing different failure states in the library.

```rust
pub enum WaySipError {
    InitFailed(String),
    DispatchError(DispatchError),
    NotSupportedProtocol(BindError),
    CursorThemeFetchFailed,
}
```

--------------------------------

### BoxInfoError Enum Definition

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/error/enum.BoxInfoError.html

The structure of the BoxInfoError enum, defining the possible error variants.

```rust
pub enum BoxInfoError {
    InvalidBoxString(String),
    InvalidBoxCoordsString(String),
    InvalidBoxSizeString(String),
    ParseFloatError(ParseFloatError),
}
```

--------------------------------

### ColorError Enum Definition

Source: https://docs.rs/libwaysip/0.7.0/libwaysip/error/enum.ColorError.html

The structure of the ColorError enum, containing variants for invalid formats and integer parsing failures.

```rust
pub enum ColorError {
    InvalidColorFormat(String),
    ParseIntError(ParseIntError),
}
```
Tokens:
Raw