pub struct Optional<T>(/* private fields */);
Expand description
An optional value.
Since D-Bus doesn’t have the concept of nullability, it uses a special value (typically the
default value) as the null value. For example this signal uses empty strings for null
values. Serde has built-in support for Option
but unfortunately that doesn’t work for us.
Hence the need for this type.
The serialization and deserialization of Optional
relies on NoneValue
implementation of
the underlying type.
§Examples
use zvariant::{serialized::Context, Optional, to_bytes, LE};
// `Null` case.
let ctxt = Context::new_dbus(LE, 0);
let s = Optional::<&str>::default();
let encoded = to_bytes(ctxt, &s).unwrap();
assert_eq!(encoded.bytes(), &[0, 0, 0, 0, 0]);
let s: Optional<&str> = encoded.deserialize().unwrap().0;
assert_eq!(*s, None);
// `Some` case.
let s = Optional::from(Some("hello"));
let encoded = to_bytes(ctxt, &s).unwrap();
assert_eq!(encoded.len(), 10);
// The first byte is the length of the string in Little-Endian format.
assert_eq!(encoded[0], 5);
let s: Optional<&str> = encoded.deserialize().unwrap().0;
assert_eq!(*s, Some("hello"));
Methods from Deref<Target = Option<T>>§
1.0.0 · sourcepub fn as_ref(&self) -> Option<&T>
pub fn as_ref(&self) -> Option<&T>
Converts from &Option<T>
to Option<&T>
.
§Examples
Calculates the length of an Option<String>
as an Option<usize>
without moving the String
. The map
method takes the self
argument by value,
consuming the original, so this technique uses as_ref
to first take an Option
to a
reference to the value inside the original.
let text: Option<String> = Some("Hello, world!".to_string());
// First, cast `Option<String>` to `Option<&String>` with `as_ref`,
// then consume *that* with `map`, leaving `text` on the stack.
let text_length: Option<usize> = text.as_ref().map(|s| s.len());
println!("still can print text: {text:?}");
1.0.0 · sourcepub fn as_mut(&mut self) -> Option<&mut T>
pub fn as_mut(&mut self) -> Option<&mut T>
Converts from &mut Option<T>
to Option<&mut T>
.
§Examples
let mut x = Some(2);
match x.as_mut() {
Some(v) => *v = 42,
None => {},
}
assert_eq!(x, Some(42));
1.75.0 · sourcepub fn as_slice(&self) -> &[T]
pub fn as_slice(&self) -> &[T]
Returns a slice of the contained value, if any. If this is None
, an
empty slice is returned. This can be useful to have a single type of
iterator over an Option
or slice.
Note: Should you have an Option<&T>
and wish to get a slice of T
,
you can unpack it via opt.map_or(&[], std::slice::from_ref)
.
§Examples
assert_eq!(
[Some(1234).as_slice(), None.as_slice()],
[&[1234][..], &[][..]],
);
The inverse of this function is (discounting
borrowing) [_]::first
:
for i in [Some(1234_u16), None] {
assert_eq!(i.as_ref(), i.as_slice().first());
}
1.75.0 · sourcepub fn as_mut_slice(&mut self) -> &mut [T]
pub fn as_mut_slice(&mut self) -> &mut [T]
Returns a mutable slice of the contained value, if any. If this is
None
, an empty slice is returned. This can be useful to have a
single type of iterator over an Option
or slice.
Note: Should you have an Option<&mut T>
instead of a
&mut Option<T>
, which this method takes, you can obtain a mutable
slice via opt.map_or(&mut [], std::slice::from_mut)
.
§Examples
assert_eq!(
[Some(1234).as_mut_slice(), None.as_mut_slice()],
[&mut [1234][..], &mut [][..]],
);
The result is a mutable slice of zero or one items that points into
our original Option
:
let mut x = Some(1234);
x.as_mut_slice()[0] += 1;
assert_eq!(x, Some(1235));
The inverse of this method (discounting borrowing)
is [_]::first_mut
:
assert_eq!(Some(123).as_mut_slice().first_mut(), Some(&mut 123))
1.40.0 · sourcepub fn as_deref(&self) -> Option<&<T as Deref>::Target>where
T: Deref,
pub fn as_deref(&self) -> Option<&<T as Deref>::Target>where
T: Deref,
Converts from Option<T>
(or &Option<T>
) to Option<&T::Target>
.
Leaves the original Option in-place, creating a new one with a reference
to the original one, additionally coercing the contents via Deref
.
§Examples
let x: Option<String> = Some("hey".to_owned());
assert_eq!(x.as_deref(), Some("hey"));
let x: Option<String> = None;
assert_eq!(x.as_deref(), None);
1.40.0 · sourcepub fn as_deref_mut(&mut self) -> Option<&mut <T as Deref>::Target>where
T: DerefMut,
pub fn as_deref_mut(&mut self) -> Option<&mut <T as Deref>::Target>where
T: DerefMut,
Converts from Option<T>
(or &mut Option<T>
) to Option<&mut T::Target>
.
Leaves the original Option
in-place, creating a new one containing a mutable reference to
the inner type’s Deref::Target
type.
§Examples
let mut x: Option<String> = Some("hey".to_owned());
assert_eq!(x.as_deref_mut().map(|x| {
x.make_ascii_uppercase();
x
}), Some("HEY".to_owned().as_mut_str()));
1.0.0 · sourcepub fn iter(&self) -> Iter<'_, T>
pub fn iter(&self) -> Iter<'_, T>
Returns an iterator over the possibly contained value.
§Examples
let x = Some(4);
assert_eq!(x.iter().next(), Some(&4));
let x: Option<u32> = None;
assert_eq!(x.iter().next(), None);
1.0.0 · sourcepub fn iter_mut(&mut self) -> IterMut<'_, T>
pub fn iter_mut(&mut self) -> IterMut<'_, T>
Returns a mutable iterator over the possibly contained value.
§Examples
let mut x = Some(4);
match x.iter_mut().next() {
Some(v) => *v = 42,
None => {},
}
assert_eq!(x, Some(42));
let mut x: Option<u32> = None;
assert_eq!(x.iter_mut().next(), None);
1.53.0 · sourcepub fn insert(&mut self, value: T) -> &mut T
pub fn insert(&mut self, value: T) -> &mut T
Inserts value
into the option, then returns a mutable reference to it.
If the option already contains a value, the old value is dropped.
See also Option::get_or_insert
, which doesn’t update the value if
the option already contains Some
.
§Example
let mut opt = None;
let val = opt.insert(1);
assert_eq!(*val, 1);
assert_eq!(opt.unwrap(), 1);
let val = opt.insert(2);
assert_eq!(*val, 2);
*val = 3;
assert_eq!(opt.unwrap(), 3);
1.20.0 · sourcepub fn get_or_insert(&mut self, value: T) -> &mut T
pub fn get_or_insert(&mut self, value: T) -> &mut T
Inserts value
into the option if it is None
, then
returns a mutable reference to the contained value.
See also Option::insert
, which updates the value even if
the option already contains Some
.
§Examples
let mut x = None;
{
let y: &mut u32 = x.get_or_insert(5);
assert_eq!(y, &5);
*y = 7;
}
assert_eq!(x, Some(7));
sourcepub fn get_or_insert_default(&mut self) -> &mut Twhere
T: Default,
🔬This is a nightly-only experimental API. (option_get_or_insert_default
)
pub fn get_or_insert_default(&mut self) -> &mut Twhere
T: Default,
option_get_or_insert_default
)1.20.0 · sourcepub fn get_or_insert_with<F>(&mut self, f: F) -> &mut Twhere
F: FnOnce() -> T,
pub fn get_or_insert_with<F>(&mut self, f: F) -> &mut Twhere
F: FnOnce() -> T,
1.80.0 · sourcepub fn take_if<P>(&mut self, predicate: P) -> Option<T>
pub fn take_if<P>(&mut self, predicate: P) -> Option<T>
Takes the value out of the option, but only if the predicate evaluates to
true
on a mutable reference to the value.
In other words, replaces self
with None
if the predicate returns true
.
This method operates similar to Option::take
but conditional.
§Examples
let mut x = Some(42);
let prev = x.take_if(|v| if *v == 42 {
*v += 1;
false
} else {
false
});
assert_eq!(x, Some(43));
assert_eq!(prev, None);
let prev = x.take_if(|v| *v == 43);
assert_eq!(x, None);
assert_eq!(prev, Some(43));
1.31.0 · sourcepub fn replace(&mut self, value: T) -> Option<T>
pub fn replace(&mut self, value: T) -> Option<T>
Replaces the actual value in the option by the value given in parameter,
returning the old value if present,
leaving a Some
in its place without deinitializing either one.
§Examples
let mut x = Some(2);
let old = x.replace(5);
assert_eq!(x, Some(5));
assert_eq!(old, Some(2));
let mut x = None;
let old = x.replace(3);
assert_eq!(x, Some(3));
assert_eq!(old, None);
Trait Implementations§
source§impl<'de, T, E> Deserialize<'de> for Optional<T>where
T: Type + NoneValue + Deserialize<'de>,
<T as NoneValue>::NoneType: Deserialize<'de> + TryInto<T, Error = E> + PartialEq,
E: Display,
impl<'de, T, E> Deserialize<'de> for Optional<T>where
T: Type + NoneValue + Deserialize<'de>,
<T as NoneValue>::NoneType: Deserialize<'de> + TryInto<T, Error = E> + PartialEq,
E: Display,
source§fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>where
D: Deserializer<'de>,
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>where
D: Deserializer<'de>,
source§impl<V> From<Optional<V>> for OwnedValue
impl<V> From<Optional<V>> for OwnedValue
source§fn from(v: Optional<V>) -> OwnedValue
fn from(v: Optional<V>) -> OwnedValue
source§impl<T: PartialEq> PartialEq for Optional<T>
impl<T: PartialEq> PartialEq for Optional<T>
source§impl<'a, T> TryFrom<OwnedValue> for Optional<T>
impl<'a, T> TryFrom<OwnedValue> for Optional<T>
impl<T: Eq> Eq for Optional<T>
impl<T> StructuralPartialEq for Optional<T>
Auto Trait Implementations§
impl<T> Freeze for Optional<T>where
T: Freeze,
impl<T> RefUnwindSafe for Optional<T>where
T: RefUnwindSafe,
impl<T> Send for Optional<T>where
T: Send,
impl<T> Sync for Optional<T>where
T: Sync,
impl<T> Unpin for Optional<T>where
T: Unpin,
impl<T> UnwindSafe for Optional<T>where
T: UnwindSafe,
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
source§default unsafe fn clone_to_uninit(&self, dst: *mut T)
default unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)