Struct async_rustbus::rustbus_core::path::ObjectPathBuf

pub struct ObjectPathBuf { /* fields omitted */ }

Implementations

impl ObjectPathBuf

An owned, mutable Dbus object path akin to String or std::path::PathBuf.

push, pop and others can be used used to modify the ObjectPathBuf in-place. ObjectPathBuf implements Deref to ObjectPath allowing for all methods on ObjectPath to be used on ObjectPathBuf.

Notes

• ObjectPathBuf is stored as a wrapper around Option<PathBuf>, where the None case is equivelent to a root path.

• As a result of the above point, root paths (a single / seperator) are special case that does not result in a heap allocation. This means that new does not result in an allocation on its own.

pub fn new() -> ObjectPathBuf

Create a new root path consisting of a single / seperator.

The ObjectPathBuf returned by this method does not result in an allocation until it is modified.

pub fn with_capacity(capacity: usize) -> ObjectPathBuf

Create a new root path and preallocate space on the heap for additions to the path.

If the size of the object path is known ahead time, this method can provide a performance benefit by avoid multiple reallocations.

When capacity is zero this method is equivelent to new.

pub fn as_object_path(&self) -> &ObjectPath

Coerces to a ObjectPath slice.

pub fn clear(&mut self)

Truncates the object path into a root path.

This does not affect the capacity of the ObjectPathBuf.

pub fn push(&mut self, path: &ObjectPath)

Append an ObjectPath to this one.

pub fn push_path<P: AsRef<Path>>(&mut self, path: P)

Append a Path to this one.

If path is invalid this method panics. If it is unknown if path is valid use [push_path_checked] instead.

Panics

path must be a valid object path with two exceptions: path can be relative or empty. If the above conditions are not met this function will panic.

Examples

use std::convert::TryFrom;
use async_rustbus::rustbus_core::path::{ObjectPath, ObjectPathBuf};
let target = ObjectPath::from_str("/example/path/to_append").unwrap();

let mut opb0  = ObjectPathBuf::try_from("/example").unwrap();
let mut opb1 = opb0.clone();
opb0.push_path("/path/to_append");
opb1.push_path("path/to_append");
assert_eq!(&opb0, target);
assert_eq!(&opb1, target);

These should panic for different reasons.

use std::convert::TryFrom;
use async_rustbus::rustbus_core::path::{ObjectPath, ObjectPathBuf};
let target = ObjectPath::from_str("/example/path/to_append").unwrap();
let mut original = ObjectPathBuf::try_from("/example").unwrap();

// Each line panics for different reasons
original.push_path("/path//consecutive/slash");
original.push_path("/p@th");

pub fn push_path_checked<P: AsRef<Path>>(
    &mut self,
    path: P
) -> Result<(), InvalidObjectPath>

Check and append path to the ObjectPathBuf if it is valid.

path must be a valid DBus object path with two exceptions: path can be relative or empty. If these conditions are not met then an Err is returned.

Examples

use std::convert::TryFrom;
use async_rustbus::rustbus_core::path::{ObjectPath, ObjectPathBuf};
let target = ObjectPath::from_str("/example/path/to_append").unwrap();

let mut opb0  = ObjectPathBuf::try_from("/example").unwrap();
let mut opb1 = opb0.clone();
opb0.push_path_checked("/path/to_append").unwrap();
opb1.push_path_checked("path/to_append").unwrap();
assert_eq!(&opb0, target);
assert_eq!(&opb1, target);

opb0.push_path_checked("/path//consecutive/slash").unwrap_err();
opb1.push_path_checked("/p@th").unwrap_err();

pub fn pop(&mut self) -> bool

Truncate the ObjectPathBuf to parent. Returns true if the path changed.

pub fn reserve(&mut self, additional: usize)

pub fn reserve_exact(&mut self, additional: usize)

pub fn capacity(&self) -> usize

Get the capacity of the current heap allocation.

If capacity is zero then there is no heap allocation, and the ObjectPathBuf is a root path. The root path is special case that can be stored without a heap allocation despite being length 1.

Methods from Deref<Target = ObjectPath>

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

Get the bytes that make up an ObjectPath.

pub fn as_str(&self) -> &str

Get the ObjectPath as a &str.

Unlike ordinary std::path::Path, ObjectPaths are always valid Rust strs making this possible.

pub fn strip_prefix<P: AsRef<Path> + ?Sized>(
    &self,
    p: &P
) -> Result<&ObjectPath, StripPrefixError>

Strip the prefix of the ObjectPath.

Unlike Path::strip_prefix this method will always leave the path will always remain absolute.

Examples

use async_rustbus::rustbus_core::path::ObjectPath;
let original  = ObjectPath::from_str("/example/path/to_strip").unwrap();
let target = ObjectPath::from_str("/path/to_strip").unwrap();
/* These two lines are equivelent because paths must always remain absolute,
   so the root '/' is readded in the second example.
   Note the second line is not a valid ObjectPath */
let stripped0 = original.strip_prefix("/example").unwrap();
let stripped1 = original.strip_prefix("/example/").unwrap();
assert_eq!(stripped0, target);
assert_eq!(stripped1, target);

original.strip_prefix("/example/other").unwrap_err();
original.strip_prefix("/example/pa").unwrap_err();

// Because the only thing stripped is the root sep this does nothing as it gets readded.
let stripped2 = original.strip_prefix("/").unwrap();
assert_eq!(stripped2, original);
let stripped3 = original.strip_prefix(original).unwrap();
assert_eq!(stripped3, ObjectPath::root_path());

pub fn parent(&self) -> Option<&ObjectPath>

Get the parent of the ObjectPath by removing the last element. If the ObjectPath is a root path then None is returned.

pub fn file_name(&self) -> Option<&str>

Retrieves the last element of the ObjectPath. If the ObjectPath is a root path then None is returned.

pub fn components(&self) -> impl Iterator<Item = &str>

Returns an Iterator over the elements of an ObjectPath.

pub fn to_object_path_buf(&self) -> ObjectPathBuf

Trait Implementations

impl AsRef<ObjectPath> for ObjectPathBuf

fn as_ref(&self) -> &ObjectPath

Performs the conversion.

impl AsRef<Path> for ObjectPathBuf

fn as_ref(&self) -> &Path

Performs the conversion.

impl AsRef<str> for ObjectPathBuf

fn as_ref(&self) -> &str

Performs the conversion.

impl Borrow<ObjectPath> for ObjectPathBuf

fn borrow(&self) -> &ObjectPath

Immutably borrows from an owned value.

impl Clone for ObjectPathBuf

fn clone(&self) -> ObjectPathBuf

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for ObjectPathBuf

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

Formats the value using the given formatter.

impl Default for ObjectPathBuf

fn default() -> ObjectPathBuf

Returns the “default value” for a type.

impl Deref for ObjectPathBuf

type Target = ObjectPath

The resulting type after dereferencing.

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

Dereferences the value.

impl Display for ObjectPathBuf

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

Formats the value using the given formatter.

impl From<&'_ ObjectPath> for ObjectPathBuf

fn from(path: &ObjectPath) -> Self

Performs the conversion.

impl From<ObjectPathBuf> for PathBuf

fn from(buf: ObjectPathBuf) -> Self

Performs the conversion.

impl From<ObjectPathBuf> for String

fn from(path: ObjectPathBuf) -> Self

Performs the conversion.

impl FromStr for ObjectPathBuf

type Err = InvalidObjectPath

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl Hash for ObjectPathBuf

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl Marshal for ObjectPathBuf

fn marshal(&self, ctx: &mut MarshalContext<'_, '_>) -> Result<(), Error>

fn marshal_as_variant(
    &self,
    ctx: &mut MarshalContext<'_, '_>
) -> Result<(), Error>

impl Ord for ObjectPathBuf

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

Restrict a value to a certain interval.

impl PartialEq<ObjectPath> for ObjectPathBuf

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

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

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

This method tests for !=.

impl PartialEq<ObjectPathBuf> for ObjectPathBuf

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

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

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

This method tests for !=.

impl PartialOrd<ObjectPathBuf> for ObjectPathBuf

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

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

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

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

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

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

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

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

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 Signature for ObjectPathBuf

fn signature() -> Type

fn alignment() -> usize

fn sig_str(s_buf: &mut SignatureBuffer)

Appends the signature of the type to the SignatureBuffer.

unsafe fn valid_slice(_bo: ByteOrder) -> bool

If this returns true, it indicates that for implementing type T, Rust’s [T] is identical to DBus’s array format and can be copied into a message after aligning the first element.

fn has_sig(sig: &str) -> bool

Check if this type fulfills this signature. This may expect to only be called with valid signatures. But it might be called with the wrong signature. This means for example you must check the length before indexing.

impl TryFrom<&'_ OsStr> for ObjectPathBuf

type Error = InvalidObjectPath

The type returned in the event of a conversion error.

fn try_from(value: &OsStr) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<&'_ Path> for ObjectPathBuf

type Error = InvalidObjectPath

The type returned in the event of a conversion error.

fn try_from(value: &Path) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<&'_ str> for ObjectPathBuf

type Error = InvalidObjectPath

The type returned in the event of a conversion error.

fn try_from(value: &str) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<OsString> for ObjectPathBuf

type Error = InvalidObjectPath

The type returned in the event of a conversion error.

fn try_from(value: OsString) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<PathBuf> for ObjectPathBuf

type Error = InvalidObjectPath

The type returned in the event of a conversion error.

fn try_from(value: PathBuf) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<String> for ObjectPathBuf

type Error = InvalidObjectPath

The type returned in the event of a conversion error.

fn try_from(value: String) -> Result<Self, Self::Error>

Performs the conversion.

impl<'buf, 'fds> Unmarshal<'buf, 'fds> for ObjectPathBuf

fn unmarshal(ctx: &mut UnmarshalContext<'fds, 'buf>) -> UnmarshalResult<Self>

impl Eq for ObjectPathBuf

impl StructuralEq for ObjectPathBuf