Struct WeakImmutableString 

pub struct WeakImmutableString<TAllocator: Allocator> { /* private fields */ }

A weak reference to the underlying ImmutableString.

This object cannot inspect the underlying string. But it does track weak references, and each weak reference can build a strong reference, assuming any other strong reference is alive.

Examples

use osom_lib_strings::immutable::{ImmutableStringError, WeakUpgradeError};
use osom_lib_strings::immutable::std::StdImmutableString;

fn main() -> Result<(), ImmutableStringError> {
    // The first instance counts as both strong and weak reference.
    let strong1 = StdImmutableString::from_str_slice("foo")?;
    assert_eq!(strong1.strong_count(), 1);
    assert_eq!(strong1.weak_count(), 1);
    assert_eq!(strong1.as_str(), "foo");

    let weak = strong1.downgrade().unwrap();  // Cheap operation
    assert_eq!(strong1.strong_count(), 1);
    assert_eq!(strong1.weak_count(), 2);
    assert_eq!(weak.strong_count(), 1);
    assert_eq!(weak.weak_count(), 2);

    let strong2 = weak.upgrade().unwrap();  // Cheap operation
    assert_eq!(strong1.strong_count(), 2);
    assert_eq!(strong1.weak_count(), 2);
    assert_eq!(weak.strong_count(), 2);
    assert_eq!(weak.weak_count(), 2);
    assert_eq!(strong2.as_str(), strong1.as_str());

    drop(strong2);
    assert_eq!(strong1.strong_count(), 1);
    assert_eq!(strong1.weak_count(), 2);
    assert_eq!(weak.strong_count(), 1);
    assert_eq!(weak.weak_count(), 2);

    drop(strong1);
    // Both counters are decreased, since there are no more strong references.
    assert_eq!(weak.strong_count(), 0);
    assert_eq!(weak.weak_count(), 1);

    // No more strong reference, .upgrade() won't work.
    assert!(matches!(weak.upgrade(), Err(WeakUpgradeError::NoStrongReferencesAlive)));

    drop(weak);  // The actual deallocation happens here.
    Ok(())
}

Implementations

impl<TAllocator: Allocator> WeakImmutableString<TAllocator>

pub fn strong_count(&self) -> u32

Returns the number of strong references to the WeakImmutableString.

pub fn weak_count(&self) -> u32

Returns the number of weak references to the WeakImmutableString.

pub fn as_str(&self) -> &str

Returns the underlying string.

Notes

Even though this is a weak reference, the string is still valid, because a sequence of chars is not Drop.

pub fn as_c_str(&self) -> &str

Returns the underlying string as C-string.

Notes

Even though this is a weak reference, the string is still valid, because a sequence of chars is not Drop.

pub fn upgrade(&self) -> Result<ImmutableString<TAllocator>, WeakUpgradeError>

Upgrades current weak reference to the strong ImmutableString.

Errors

For details see WeakUpgradeError.

pub fn abandon(self) -> bool

Abandons current weak reference.

If the internal weak counter is positive it returns false.

Otherwise it deallocates the underlying memory and returns true. In particular only single (the last) WeakImmutableString returns true by calling this.

Trait Implementations

impl<TAllocator: Allocator> Clone for WeakImmutableString<TAllocator>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<TAllocator: Debug + Allocator> Debug for WeakImmutableString<TAllocator>

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

Formats the value using the given formatter.

impl<TAllocator: Allocator> ReprC for WeakImmutableString<TAllocator>

const CHECK: ()

This field is used for const checks only.

impl<TAllocator: Allocator> TryClone for WeakImmutableString<TAllocator>

type Error = MaxReferencesExceededError

fn try_clone(&self) -> Result<Self, Self::Error>

Tries to clone the type.