Struct Retained

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

A reference counted pointer type for Objective-C objects.

Retained strongly references or “retains” the given object T, and decrements the retain count or “releases” it again when dropped, thereby ensuring it will be deallocated at the right time.

The type T inside Retained<T> can be anything that implements Message.

This can usually be gotten from one of the methods in the framework crates, but can also be created manually with the msg_send! macro, or even more manually with the Retained::retain, Retained::from_raw and Retained::retain_autoreleased methods.

Comparison to std types

Retained<T> is the Objective-C equivalent of Arc, that is, it is a thread-safe reference-counting pointer, and allows cloning by bumping the reference count, and weak references using rc::Weak.

Unlike Arc, objects can be retained directly from a &T using Message::retain (for Arc you need &Arc<T>).

Even though most Objective-C types aren’t thread safe, Objective-C has no concept of Rc. Retain/release operations are always atomic.

Forwarding implementations

Since Retained<T> is a smart pointer, it Derefs to T.

It also forwards the implementation of a bunch of standard library traits such as PartialEq, AsRef, and so on, so that it becomes possible to use e.g. Retained<NSString> as if it was NSString. Note that having NSString directly is not possible since Objective-C objects cannot live on the stack, but instead must reside on the heap, and as such must be accessed behind a pointer or a reference (i.e. &NSString).

Note that because of current limitations in the Rust trait system, some traits like Default, IntoIterator, FromIterator, From and Into are not directly implementable on NSString; for that use-case, we instead provide the DefaultRetained, RetainedIntoIterator and RetainedFromIterator traits, which make some of the the aforementioned traits implementable on Retained.

Memory layout

This is guaranteed to have the same size and alignment as a pointer to the object, *const T.

Additionally, it participates in the null-pointer optimization, that is, Option<Retained<T>> is guaranteed to have the same size as Retained<T>.

Example

Various usage of Retained on an immutable object.

use objc2_foundation::{NSObject, NSString};
use objc2::rc::Retained;
use objc2::{ClassType, msg_send};

// Use `msg_send!` to create an `Retained` with correct memory management
//
// SAFETY: The types are correct, and it is safe to call the `new`
// selector on `NSString`.
let string: Retained<NSString> = unsafe { msg_send![NSString::class(), new] };
// Or:
// let string = NSString::new();

// Methods on `NSString` is usable via `Deref`
assert_eq!(string.length(), 0);

// Bump the reference count of the object.
let another_ref: Retained<NSString> = string.clone();

// Convert one of the references to a reference to `NSObject` instead
let obj: Retained<NSObject> = string.into_super();

// And use the `Debug` impl from that
assert_eq!(format!("{obj:?}"), "");

// Finally, the `Retained`s go out of scope, the reference counts are
// decreased, and the string will deallocate

Implementations

impl<T: ?Sized + Message> Retained<T>

pub unsafe fn from_raw(ptr: *mut T) -> Option<Self>

Construct an Retained from a pointer that already has +1 retain count.

Returns None if the pointer was NULL.

This is useful when you have a retain count that has been handed off from somewhere else, usually Objective-C methods like init, alloc, new, copy, or methods with the ns_returns_retained attribute.

If you do not have +1 retain count, such as if your object was retrieved from other methods than the ones noted above, use Retained::retain instead.

Safety

You must uphold the same requirements as described in Retained::retain.

Additionally, you must ensure the given object pointer has +1 retain count.

Example

Comparing different ways of creating a new NSObject.

use objc2::rc::Retained;
use objc2::runtime::NSObject;
use objc2::{msg_send, AnyThread, ClassType};

// Manually using `msg_send!`, pointers and `Retained::from_raw`
let obj: *mut NSObject = unsafe { msg_send![NSObject::class(), alloc] };
let obj: *mut NSObject = unsafe { msg_send![obj, init] };
// SAFETY: `-[NSObject init]` returns +1 retain count
let obj: Retained<NSObject> = unsafe { Retained::from_raw(obj).unwrap() };

// Or automatically by specifying `Retained` as the return value from
// `msg_send!` (it will do the correct conversion internally).
let obj: Retained<NSObject> = unsafe { msg_send![NSObject::alloc(), init] };

// Or using the `NSObject::new` method
let obj = NSObject::new();

pub unsafe fn new(ptr: *mut T) -> Option<Self>

👎Deprecated: use the more descriptive name Retained::from_raw instead

Deprecated alias for Retained::from_raw, see that for details.

Safety

Same as Retained::from_raw.

pub fn into_raw(this: Self) -> *mut T

Consumes the Retained, returning a raw pointer with +1 retain count.

After calling this function, the caller is responsible for the memory previously managed by the Retained.

This is effectively the opposite of Retained::from_raw, see that for more details on when this function is useful.

Examples

Converting an Retained to a pointer and back.

use objc2::rc::Retained;
use objc2::runtime::NSObject;

let obj = NSObject::new();
let ptr = Retained::into_raw(obj);
// SAFETY: The pointer is valid, and has +1 retain count from above.
let obj = unsafe { Retained::from_raw(ptr) }.unwrap();

pub fn as_ptr(this: &Self) -> *const T

Returns a raw pointer to the object.

The pointer is valid for at least as long as the Retained is held.

This is an associated method, and must be called as Retained::as_ptr(obj).

impl<T: Message> Retained<T>

pub fn downcast<U: DowncastTarget>(self) -> Result<Retained<U>, Retained<T>>

where Self: 'static,

Attempt to downcast the object to a class of type U.

See AnyObject::downcast_ref for more details.

Errors

If casting failed, this will return the object back as the Err type. If you do not care about this, and just want an Option, use .downcast().ok().

Example

Cast a string to an object, and back again.

use objc2_foundation::{NSString, NSObject};

let string = NSString::new();
// The string is an object
let obj = string.downcast::<NSObject>().unwrap();
// And it is also a string
let string = obj.downcast::<NSString>().unwrap();

Try to cast an object to a string, which will fail and return the object in Err.

use objc2_foundation::{NSString, NSObject};

let obj = NSObject::new();
let obj = obj.downcast::<NSString>().unwrap_err();

pub unsafe fn cast_unchecked<U: Message>(this: Self) -> Retained<U>

Convert the type of the given object to another.

This is equivalent to a cast between two pointers.

See Retained::into_super, ProtocolObject::from_retained and Retained::downcast for safe alternatives.

This is common to do when you know that an object is a subclass of a specific class (e.g. casting an instance of NSString to NSObject is safe because NSString is a subclass of NSObject), but do not want to pay the (very slight) performance price of dynamically checking that precondition with a downcast.

All 'static objects can safely be cast to AnyObject, since that assumes no specific class.

This is an associated method, and must be called as Retained::cast_unchecked(obj).

Safety

You must ensure that the object can be reinterpreted as the given type.

If T is not 'static, you must ensure that U ensures that the data contained by T is kept alive for as long as U lives.

Additionally, you must ensure that any safety invariants that the new type has are upheld.

pub unsafe fn cast<U: Message>(this: Self) -> Retained<U>

👎Deprecated: Use downcast, or cast_unchecked instead

Deprecated alias of Retained::cast_unchecked.

Safety

See Retained::cast_unchecked.

pub unsafe fn retain(ptr: *mut T) -> Option<Retained<T>>

Retain the pointer and construct an Retained from it.

Returns None if the pointer was NULL.

This is useful when you have been given a pointer to an object from some API, and you would like to ensure that the object stays around while you work on it.

For normal Objective-C methods, you may want to use Retained::retain_autoreleased instead, as that is usually more performant.

See also Message::retain for a safe alternative where you already have a reference to the object.

Safety

The pointer must be valid as a reference (aligned, dereferenceable and initialized, see the std::ptr module for more information), or NULL.

You must ensure that any data that T may reference lives for at least as long as T.

pub unsafe fn retain_autoreleased(ptr: *mut T) -> Option<Retained<T>>

Retains a previously autoreleased object pointer.

This is useful when calling Objective-C methods that return autoreleased objects, see Cocoa’s Memory Management Policy.

This has exactly the same semantics as Retained::retain, except it can sometimes avoid putting the object into the autorelease pool, possibly yielding increased speed and reducing memory pressure.

Note: This relies heavily on being inlined right after msg_send!, be careful to not accidentally require instructions between these.

Safety

Same as Retained::retain.

pub fn autorelease_ptr(this: Self) -> *mut T

Autoreleases the Retained, returning a pointer.

The object is not immediately released, but will be when the innermost / current autorelease pool is drained.

This is useful when defining your own classes and you have some error parameter passed as Option<&mut *mut NSError>, and you want to create and autorelease an error before returning.

This is an associated method, and must be called as Retained::autorelease_ptr(obj).

Safety

This method is safe to call, but the returned pointer is only guaranteed to be valid until the innermost autorelease pool is drained.

pub unsafe fn autorelease<'p>(this: Self, pool: AutoreleasePool<'p>) -> &'p T

Autoreleases the Retained, returning a reference bound to the pool.

The object is not immediately released, but will be when the innermost / current autorelease pool (given as a parameter) is drained.

This is an associated method, and must be called as Retained::autorelease(obj, pool).

Safety

The given pool must represent the innermost pool, to ensure that the reference is not moved outside the autorelease pool into which it has been put in.

pub fn autorelease_return(this: Self) -> *mut T

Autoreleases and prepares the Retained to be returned to Objective-C.

The object is not immediately released, but will be when the innermost autorelease pool is drained.

This is useful when defining your own methods where you will often find yourself in need of returning autoreleased objects to properly follow Cocoa’s Memory Management Policy.

To that end, you could also use Retained::autorelease_ptr, but this is more efficient than a normal autorelease, since it makes a best effort attempt to hand off ownership of the retain count to a subsequent call to objc_retainAutoreleasedReturnValue / Retained::retain_autoreleased in the enclosing call frame.

This optimization relies heavily on this function being tail called, so make sure you only call this function at the end of your method.

Example

Returning an Retained from a custom method (note: the define_class! macro supports doing this for you automatically).

use objc2::{class, msg_send, sel};
use objc2::rc::Retained;
use objc2::runtime::{AnyClass, AnyObject, ClassBuilder, Sel};

let mut builder = ClassBuilder::new(c"ExampleObject", class!(NSObject)).unwrap();

extern "C-unwind" fn get(cls: &AnyClass, _cmd: Sel) -> *mut AnyObject {
    let obj: Retained<AnyObject> = unsafe { msg_send![cls, new] };
    Retained::autorelease_return(obj)
}

unsafe {
    builder.add_class_method(
        sel!(get),
        get as extern "C-unwind" fn(_, _) -> _,
    );
}

let cls = builder.register();

impl<T: ClassType + 'static> Retained<T>

where T::Super: 'static,

pub fn into_super(self) -> Retained<T::Super>

Convert the object into its superclass.

Trait Implementations

impl<T: ?Sized + AsRef<U>, U: ?Sized> AsRef<U> for Retained<T>

fn as_ref(&self) -> &U

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

impl<T: Binary + ?Sized> Binary for Retained<T>

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

Formats the value using the given formatter.

impl<T: ?Sized> Borrow<T> for Retained<T>

fn borrow(&self) -> &T

Immutably borrows from an owned value.

impl<T: Message> Clone for Retained<T>

fn clone(&self) -> Self

Retain the object, increasing its reference count.

This is equivalent to Message::retain.

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

Performs copy-assignment from source.

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

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

Formats the value using the given formatter.

impl<T: ?Sized + DefaultRetained> Default for Retained<T>

fn default() -> Self

Returns the “default value” for a type.

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

fn deref(&self) -> &T

Obtain an immutable reference to the object.

type Target = T

The resulting type after dereferencing.

impl<T: Display + ?Sized> Display for Retained<T>

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

Formats the value using the given formatter.

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

#[may_dangle] (see this) doesn’t apply here since we don’t run T’s destructor (rather, we want to discourage having Ts with a destructor); and even if we did run the destructor, it would not be safe to add since we cannot verify that a dealloc method doesn’t access borrowed data.

fn drop(&mut self)

Releases the retained object.

The contained object’s destructor (Drop impl, if it has one) is never run - override the dealloc method instead (which define_class! does for you).

impl<T: ?Sized + Error> Error for Retained<T>

Available on crate feature std only.

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0: use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0: replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

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

Provides type-based access to context intended for error reports.

impl<'a, A, T: ?Sized> Extend<A> for &'a Retained<T>

where &'a T: Extend<A>,

fn extend<I: IntoIterator<Item = A>>(&mut self, iter: I)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

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

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

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

Reserves capacity in a collection for the given number of additional elements.

impl<A, T: ?Sized> Extend<A> for Retained<T>

where for<'a> &'a T: Extend<A>,

fn extend<I: IntoIterator<Item = A>>(&mut self, iter: I)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

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

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

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

Reserves capacity in a collection for the given number of additional elements.

impl<T: Message> From<&Retained<T>> for Weak<T>

fn from(obj: &Retained<T>) -> Self

Converts to this type from the input type.

impl<T: ?Sized + AsRef<U>, U: Message> From<&T> for Retained<U>

fn from(obj: &T) -> Self

Cast the object to its superclass, and retain it.

impl<P: ?Sized + 'static> From<Retained<ProtocolObject<P>>> for Retained<AnyObject>

fn from(obj: Retained<ProtocolObject<P>>) -> Self

Convert the protocol object to AnyObject.

impl<T: ClassType + 'static> From<Retained<T>> for Retained<AnyObject>

fn from(obj: Retained<T>) -> Self

Convert the object to AnyObject.

impl<T: Message> From<Retained<T>> for Weak<T>

fn from(obj: Retained<T>) -> Self

Converts to this type from the input type.

impl<T, U: RetainedFromIterator<T>> FromIterator<T> for Retained<U>

fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> Self

Creates a value from an iterator.

impl<'a, T: ?Sized> Future for &'a Retained<T>

where &'a T: Future,

type Output = <&'a T as Future>::Output

The type of value produced on completion.

fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output>

Attempts to resolve the future to a final value, registering the current task for wakeup if the value is not yet available.

impl<T: Hash + ?Sized> Hash for Retained<T>

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, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<'a, T: ?Sized> Hasher for &'a Retained<T>

where &'a T: Hasher,

fn finish(&self) -> u64

Returns the hash value for the values written so far.

fn write(&mut self, bytes: &[u8])

Writes some data into this Hasher.

fn write_u8(&mut self, i: u8)

Writes a single u8 into this hasher.

fn write_u16(&mut self, i: u16)

Writes a single u16 into this hasher.

fn write_u32(&mut self, i: u32)

Writes a single u32 into this hasher.

fn write_u64(&mut self, i: u64)

Writes a single u64 into this hasher.

fn write_u128(&mut self, i: u128)

Writes a single u128 into this hasher.

fn write_usize(&mut self, i: usize)

Writes a single usize into this hasher.

fn write_i8(&mut self, i: i8)

Writes a single i8 into this hasher.

fn write_i16(&mut self, i: i16)

Writes a single i16 into this hasher.

fn write_i32(&mut self, i: i32)

Writes a single i32 into this hasher.

fn write_i64(&mut self, i: i64)

Writes a single i64 into this hasher.

fn write_i128(&mut self, i: i128)

Writes a single i128 into this hasher.

fn write_isize(&mut self, i: isize)

Writes a single isize into this hasher.

fn write_length_prefix(&mut self, len: usize)

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

Writes a length prefix into this hasher, as part of being prefix-free.

fn write_str(&mut self, s: &str)

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

Writes a single str into this hasher.

impl<T: ?Sized> Hasher for Retained<T>

where for<'a> &'a T: Hasher,

fn finish(&self) -> u64

Returns the hash value for the values written so far.

fn write(&mut self, bytes: &[u8])

Writes some data into this Hasher.

fn write_u8(&mut self, i: u8)

Writes a single u8 into this hasher.

fn write_u16(&mut self, i: u16)

Writes a single u16 into this hasher.

fn write_u32(&mut self, i: u32)

Writes a single u32 into this hasher.

fn write_u64(&mut self, i: u64)

Writes a single u64 into this hasher.

fn write_u128(&mut self, i: u128)

Writes a single u128 into this hasher.

fn write_usize(&mut self, i: usize)

Writes a single usize into this hasher.

fn write_i8(&mut self, i: i8)

Writes a single i8 into this hasher.

fn write_i16(&mut self, i: i16)

Writes a single i16 into this hasher.

fn write_i32(&mut self, i: i32)

Writes a single i32 into this hasher.

fn write_i64(&mut self, i: i64)

Writes a single i64 into this hasher.

fn write_i128(&mut self, i: i128)

Writes a single i128 into this hasher.

fn write_isize(&mut self, i: isize)

Writes a single isize into this hasher.

fn write_length_prefix(&mut self, len: usize)

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

Writes a length prefix into this hasher, as part of being prefix-free.

fn write_str(&mut self, s: &str)

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

Writes a single str into this hasher.

impl<'a, T: ?Sized> IntoIterator for &'a Retained<T>

where &'a T: IntoIterator,

type Item = <&'a T as IntoIterator>::Item

The type of the elements being iterated over.

type IntoIter = <&'a T as IntoIterator>::IntoIter

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<T: ?Sized + RetainedIntoIterator> IntoIterator for Retained<T>

type Item = <T as RetainedIntoIterator>::Item

The type of the elements being iterated over.

type IntoIter = <T as RetainedIntoIterator>::IntoIter

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<T: LowerExp + ?Sized> LowerExp for Retained<T>

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

Formats the value using the given formatter.

impl<T: LowerHex + ?Sized> LowerHex for Retained<T>

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

Formats the value using the given formatter.

impl<T: Octal + ?Sized> Octal for Retained<T>

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

Formats the value using the given formatter.

impl<T: Ord + ?Sized> Ord for Retained<T>

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<T: ?Sized + PartialEq<U>, U: ?Sized> PartialEq<Retained<U>> for Retained<T>

fn eq(&self, other: &Retained<U>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Retained<U>) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: ?Sized + PartialOrd<U>, U: ?Sized> PartialOrd<Retained<U>> for Retained<T>

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

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

fn lt(&self, other: &Retained<U>) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Retained<U>) -> bool

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

fn ge(&self, other: &Retained<U>) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

fn gt(&self, other: &Retained<U>) -> bool

Tests greater than (for self and other) and is used by the > operator.

impl<T: ?Sized> Pointer for Retained<T>

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

Formats the value using the given formatter.

impl<'a, T: ?Sized> Read for &'a Retained<T>

where &'a T: Read,

Available on crate feature std only.

fn read(&mut self, buf: &mut [u8]) -> Result<usize>

Pull some bytes from this source into the specified buffer, returning how many bytes were read.

fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize>

Like read, except that it reads into a slice of buffers.

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize>

Reads all bytes until EOF in this source, placing them into buf.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize>

Reads all bytes until EOF in this source, appending them to buf.

fn read_exact(&mut self, buf: &mut [u8]) -> Result<()>

Reads the exact number of bytes required to fill buf.

fn is_read_vectored(&self) -> bool

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

Determines if this Reader has an efficient read_vectored implementation.

fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>

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

Pull some bytes from this source into the specified buffer.

fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>

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

Reads the exact number of bytes required to fill cursor.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adaptor for this instance of Read.

fn bytes(self) -> Bytes<Self>

where Self: Sized,

Transforms this Read instance to an Iterator over its bytes.

fn chain<R>(self, next: R) -> Chain<Self, R>

where R: Read, Self: Sized,

Creates an adapter which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

where Self: Sized,

Creates an adapter which will read at most limit bytes from it.

impl<T: ?Sized> Read for Retained<T>

where for<'a> &'a T: Read,

Available on crate feature std only.

fn read(&mut self, buf: &mut [u8]) -> Result<usize>

Pull some bytes from this source into the specified buffer, returning how many bytes were read.

fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize>

Like read, except that it reads into a slice of buffers.

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize>

Reads all bytes until EOF in this source, placing them into buf.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize>

Reads all bytes until EOF in this source, appending them to buf.

fn read_exact(&mut self, buf: &mut [u8]) -> Result<()>

Reads the exact number of bytes required to fill buf.

fn is_read_vectored(&self) -> bool

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

Determines if this Reader has an efficient read_vectored implementation.

fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>

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

Pull some bytes from this source into the specified buffer.

fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>

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

Reads the exact number of bytes required to fill cursor.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adaptor for this instance of Read.

fn bytes(self) -> Bytes<Self>

where Self: Sized,

Transforms this Read instance to an Iterator over its bytes.

fn chain<R>(self, next: R) -> Chain<Self, R>

where R: Read, Self: Sized,

Creates an adapter which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

where Self: Sized,

Creates an adapter which will read at most limit bytes from it.

impl<'a, T: ?Sized> Seek for &'a Retained<T>

where &'a T: Seek,

Available on crate feature std only.

fn seek(&mut self, pos: SeekFrom) -> Result<u64>

Seek to an offset, in bytes, in a stream.

fn stream_position(&mut self) -> Result<u64>

Returns the current seek position from the start of the stream.

fn rewind(&mut self) -> Result<(), Error>

Rewind to the beginning of a stream.

fn stream_len(&mut self) -> Result<u64, Error>

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

Returns the length of this stream (in bytes).

fn seek_relative(&mut self, offset: i64) -> Result<(), Error>

Seeks relative to the current position.

impl<T: ?Sized> Seek for Retained<T>

where for<'a> &'a T: Seek,

Available on crate feature std only.

fn seek(&mut self, pos: SeekFrom) -> Result<u64>

Seek to an offset, in bytes, in a stream.

fn stream_position(&mut self) -> Result<u64>

Returns the current seek position from the start of the stream.

fn rewind(&mut self) -> Result<(), Error>

Rewind to the beginning of a stream.

fn stream_len(&mut self) -> Result<u64, Error>

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

Returns the length of this stream (in bytes).

fn seek_relative(&mut self, offset: i64) -> Result<(), Error>

Seeks relative to the current position.

impl<T: UpperExp + ?Sized> UpperExp for Retained<T>

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

Formats the value using the given formatter.

impl<T: UpperHex + ?Sized> UpperHex for Retained<T>

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

Formats the value using the given formatter.

impl<'a, T: ?Sized> Write for &'a Retained<T>

where &'a T: Write,

fn write_str(&mut self, s: &str) -> Result

Writes a string slice into this writer, returning whether the write succeeded.

fn write_char(&mut self, c: char) -> Result

Writes a char into this writer, returning whether the write succeeded.

fn write_fmt(&mut self, args: Arguments<'_>) -> Result

Glue for usage of the write! macro with implementors of this trait.

impl<'a, T: ?Sized> Write for &'a Retained<T>

where &'a T: Write,

Available on crate feature std only.

fn write(&mut self, buf: &[u8]) -> Result<usize>

Writes a buffer into this writer, returning how many bytes were written.

fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize>

Like write, except that it writes from a slice of buffers.

fn flush(&mut self) -> Result<()>

Flushes this output stream, ensuring that all intermediately buffered contents reach their destination.

fn write_all(&mut self, buf: &[u8]) -> Result<()>

Attempts to write an entire buffer into this writer.

fn write_fmt(&mut self, fmt: Arguments<'_>) -> Result<()>

Writes a formatted string into this writer, returning any error encountered.

fn is_write_vectored(&self) -> bool

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

Determines if this Writer has an efficient write_vectored implementation.

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>

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

Attempts to write multiple buffers into this writer.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Write.

impl<T: ?Sized> Write for Retained<T>

where for<'a> &'a T: Write,

Available on crate feature std only.

fn write(&mut self, buf: &[u8]) -> Result<usize>

Writes a buffer into this writer, returning how many bytes were written.

fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize>

Like write, except that it writes from a slice of buffers.

fn flush(&mut self) -> Result<()>

Flushes this output stream, ensuring that all intermediately buffered contents reach their destination.

fn write_all(&mut self, buf: &[u8]) -> Result<()>

Attempts to write an entire buffer into this writer.

fn write_fmt(&mut self, fmt: Arguments<'_>) -> Result<()>

Writes a formatted string into this writer, returning any error encountered.

fn is_write_vectored(&self) -> bool

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

Determines if this Writer has an efficient write_vectored implementation.

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>

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

Attempts to write multiple buffers into this writer.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Write.

impl<T: Eq + ?Sized> Eq for Retained<T>

impl<T: ?Sized + RefUnwindSafe> RefUnwindSafe for Retained<T>

impl<T: ?Sized + Sync + Send> Send for Retained<T>

Retained<T> is Send if T is Send + Sync.

impl<T: ?Sized + Sync + Send> Sync for Retained<T>

Retained<T> is Sync if T is Send + Sync.

impl<T: ?Sized> Unpin for Retained<T>

impl<T: ?Sized + RefUnwindSafe> UnwindSafe for Retained<T>