counting_pointer::Asc - Rust
Description: API documentation for the Rust `Asc` struct in crate `counting_pointer`.
Keywords: rust, rustlang, rust-lang, Asc

# [−][src]Struct counting_pointer::Asc

    pub struct Asc<T: ?Sized, A = System> where
        A: GlobalAlloc,  { /* fields omitted */ }

A thread-safe strong reference-counting pointer. 'Asc' stands for 'Atomic Strong Counted.'

It behaves like `std::Sync::Arc` except for that this treats only strong pointer; i.e. `Asc` gives up weak pointer for the performance.

The inherent methods of `Asc` are all associated funcitons, which means that you have to call them as e.g., `Asc::get_mut(&mut value)` instead of `value.get_mut()` . This avoids conflicts with methods of the inner type `T` .

# Thread Safety

Unlike to `Sc` , `Asc` uses atomic operations for its reference counting. This means that it is thread-safe. The disadvangate is that atomic operations are more expensive than ordinary memory access.

## Implementations

### `impl<T, A> Asc<T, A> where
A: GlobalAlloc,` [src]

#### `pub fn new(val: T, alloc: A) -> Self`[src]

Creates a new instance.

# Examples

    use std::alloc::System;
    use counting_pointer::Asc;

    let _five = Asc::new(5, System);

#### `pub fn from_slice_alloc(vals: &[T], alloc: A) -> Asc<[T], A> where
T: Clone,` [src]

Creates a new instance of `Asc<[T], A>` .

# Examples

    use std::alloc::System;
    use counting_pointer::Asc;

    let vals: [i32; 4] = [0, 1, 2, 3];
    let sc = Asc::from_slice_alloc(&vals, System);
    assert_eq!(&vals, &*sc);

### `impl<A> Asc<dyn Any, A> where
A: GlobalAlloc,` [src]

#### `pub fn new_any<T>(val: T, alloc: A) -> Self where
T: Any,` [src]

Creates `Asc<dyn Any>` instance.

# Examples

    use std::alloc::System;
    use counting_pointer::Asc;

    let _five = Asc::new_any(5, System);

### `impl<T, A> Asc<T, A> where
A: GlobalAlloc,` [src]

#### `pub fn to_any(this: Self) -> Asc<dyn Any, A> where
T: Any,` [src]

Consumes `this`, returning `Asc<dyn Any, A>`

# Examples

    use counting_pointer::Asc;

    let sc: Asc<i32> = Asc::from(6);
    let any = Asc::to_any(sc);

### `impl<T: ?Sized, A> Asc<T, A> where
A: GlobalAlloc,` [src]

#### `pub fn as_ptr(this: &Self) -> *const T`[src]

Provides a raw pointer to the data.

The counts are not affected in any way and the `Asc` is not consumed. The pointer is valid for as long as another `Asc` instance is pointing to the address.

# Examples

    use counting_pointer::Asc;

    let x: Asc<String> = Asc::from(String::from("Hello"));
    let x_ptr = Asc::as_ptr(&x);
    assert_eq!("Hello", unsafe { &*x_ptr });

#### `pub fn count(this: &Self) -> usize`[src]

Returns the number of `Asc` pointers pointing to the same address.

# Examples

    use counting_pointer::Asc;

    let five: Asc<i32> = Asc::from(5);
    assert_eq!(1, Asc::count(&five));

    let _also_five = five.clone();
    assert_eq!(2, Asc::count(&five));
    assert_eq!(2, Asc::count(&_also_five));

    drop(five);
    assert_eq!(1, Asc::count(&_also_five));

#### `pub fn get_mut(this: &mut Self) -> Option<&mut T>`[src]

Returns a mutable reference into the given `Asc` , if no other `Asc` instance is pointing to the same address; otherwise returns `None` .

See also `make_mut` , which will `clone` the inner value when some other `Asc` instances are.

# Examples

    use counting_pointer::Asc;

    let mut x: Asc<i32> = Asc::from(3);
    assert_eq!(3, *x);

    *Asc::get_mut(&mut x).unwrap() = 4;
    assert_eq!(4, *x);

    let _y = x.clone();
    let n = Asc::get_mut(&mut x);
    assert!(n.is_none());

#### `pub fn ptr_eq(this: &Self, other: &Self) -> bool`[src]

Returns `true` if the two `Asc` instances point to the same address, or `false` .

# Examples

    use counting_pointer::Asc;

    let five: Asc<i32> = Asc::from(5);
    let same_five = five.clone();
    let other_five: Asc<i32> = Asc::from(5);

    assert_eq!(true, Asc::ptr_eq(&five, &same_five));
    assert_eq!(false, Asc::ptr_eq(&five, &other_five));

#### `pub fn into_raw_alloc(this: Self) -> (*const T, A)`[src]

Consumes `this` , returning the wrapped pointer and the allocator.

To avoid memory leak, the returned pointer must be converted back to an `Asc` using `from_raw_alloc` .

Using this function and `from_raw_alloc` , user can create an `Asc<T: ?Sized>` instance.

# Examples

    use counting_pointer::Asc;

    let asc: Asc<String> = Asc::from("Foo".to_string());
    let (ptr, alloc) = Asc::into_raw_alloc(asc);
    let _asc: Asc<dyn AsRef<str>> = unsafe { Asc::from_raw_alloc(ptr, alloc) };

#### `pub unsafe fn from_raw_alloc(ptr: *const T, alloc: A) -> Self`[src]

Constructs a new instance from a raw pointer and allocator.

The raw pointer must have been previously returned by a call to `into_raw_alloc` .

Using this function and `into_raw_alloc` , user can create an `Asc<T: ?Sized>` instance.

# Safety

It may lead to memory unsafety to use improperly, even if the returned value will never be accessed.

# Examples

    use counting_pointer::Asc;

    let asc: Asc<String> = Asc::from("Foo".to_string());
    let (ptr, alloc) = Asc::into_raw_alloc(asc);
    let _asc: Asc<dyn AsRef<str>> = unsafe { Asc::from_raw_alloc(ptr, alloc) };

### `impl<T: Clone, A: Clone> Asc<T, A> where
A: GlobalAlloc,` [src]

#### `pub fn make_mut(this: &mut Self) -> &mut T`[src]

Makes a mutable reference into the given `Asc` .

If another `Asc` instance is pointing to the same address, `make_mut` will `clone` the inner value to a new allocation to ensure unique ownership.

See also `get_mut` , which will fail rather than cloning.

# Examples

    use counting_pointer::Asc;

    let mut data: Asc<i32> = Asc::from(5);
    assert_eq!(5, *data);

    *Asc::make_mut(&mut data) += 1; // Won't clone anything.
    assert_eq!(6, *data);

    let mut data2 = data.clone();  // Won't clone the inner data.
    *Asc::make_mut(&mut data) += 1; // Clones inner data.
    assert_eq!(7, *data);
    assert_eq!(6, *data2);

### `impl<A> Asc<dyn Any, A> where
A: GlobalAlloc,` [src]

#### `pub fn downcast<T: Any>(self) -> Result<Asc<T, A>, Self>`[src]

Attempts to downcast the `Asc<dyn Any, A>` to a concrete type.

# Examples

    use std::alloc::System;
    use std::any::Any;
    use counting_pointer::Asc;

    let sc = Asc::new_any(8 as i32, System);

    let success = Asc::downcast::<i32>(sc.clone()).unwrap();
    assert_eq!(8, *success);

    let fail = Asc::downcast::<String>(sc.clone());
    assert_eq!(true, fail.is_err());

## Trait Implementations

### `impl<T: ?Sized, A> AsRef<T> for Asc<T, A> where
A: GlobalAlloc,` [src]

#### `fn as_ref(&self) -> &T`[src]

Performs the conversion.

### `impl<T: ?Sized, A> Borrow<T> for Asc<T, A> where
A: GlobalAlloc,` [src]

#### `fn borrow(&self) -> &T`[src]

Immutably borrows from an owned value. Read more

### `impl<T: ?Sized, A> Clone for Asc<T, A> where
A: Clone + GlobalAlloc,` [src]

#### `fn clone(&self) -> Self`[src]

Returns a copy of the value. Read more

#### `fn clone_from(&mut self, source: &Self)`1.0.0[src]

Performs copy-assignment from `source`. Read more

### `impl<T: ?Sized, A> Debug for Asc<T, A> where
A: Debug + GlobalAlloc,` [src]

#### `fn fmt(&self, f: &mut Formatter<'_>) -> Result`[src]

Formats the value using the given formatter. Read more

### `impl<T, A> Default for Asc<T, A> where
T: Default,
A: Default + GlobalAlloc,` [src]

#### `fn default() -> Self`[src]

Returns the "default value" for a type. Read more

### `impl<T: ?Sized, A> Deref for Asc<T, A> where
A: GlobalAlloc,` [src]

#### `type Target = T`

The resulting type after dereferencing.

#### `fn deref(&self) -> &Self::Target`[src]

Dereferences the value.

### `impl<T: ?Sized, A> Display for Asc<T, A> where
T: Display,
A: GlobalAlloc,` [src]

#### `fn fmt(&self, f: &mut Formatter<'_>) -> Result`[src]

Formats the value using the given formatter. Read more

### `impl<T: ?Sized, A> Drop for Asc<T, A> where
A: GlobalAlloc,` [src]

#### `fn drop(&mut self)`[src]

Executes the destructor for this type. Read more

### `impl<T: ?Sized, A> Eq for Asc<T, A> where
T: Eq,
A: GlobalAlloc,` [src]

### `impl<T, A, '_> From<&'_ [T]> for Asc<[T], A> where
T: Clone,
A: Default + GlobalAlloc,` [src]

#### `fn from(vals: &[T]) -> Self`[src]

Performs the conversion.

### `impl<T, A> From<T> for Asc<T, A> where
A: Default + GlobalAlloc,` [src]

#### `fn from(val: T) -> Self`[src]

Performs the conversion.

### `impl<T: ?Sized, A> Hash for Asc<T, A> where
T: Hash,
A: GlobalAlloc,` [src]

#### `fn hash<H>(&self, hasher: &mut H) where
H: Hasher,` [src]

Feeds this value into the given `Hasher`. Read more

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

Feeds a slice of this type into the given `Hasher`. Read more

### `impl<T: ?Sized, A> Ord for Asc<T, A> where
T: Ord,
A: GlobalAlloc,` [src]

#### `fn cmp(&self, other: &Self) -> Ordering`[src]

This method returns an `Ordering` between `self` and `other`. Read more

#### `#[must_use]fn max(self, other: Self) -> Self` 1.21.0[src]

Compares and returns the maximum of two values. Read more

#### `#[must_use]fn min(self, other: Self) -> Self` 1.21.0[src]

Compares and returns the minimum of two values. Read more

#### `#[must_use]fn clamp(self, min: Self, max: Self) -> Self`[src]

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

Restrict a value to a certain interval. Read more

### `impl<T: ?Sized, A> PartialEq<Asc<T, A>> for Asc<T, A> where
T: PartialEq,
A: GlobalAlloc,` [src]

#### `fn eq(&self, other: &Self) -> bool`[src]

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

#### `#[must_use]fn ne(&self, other: &Rhs) -> bool` 1.0.0[src]

This method tests for `!=`.

### `impl<T: ?Sized, A> PartialOrd<Asc<T, A>> for Asc<T, A> where
T: PartialOrd,
A: GlobalAlloc,` [src]

#### `fn partial_cmp(&self, other: &Self) -> Option<Ordering>`[src]

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

#### `#[must_use]fn lt(&self, other: &Rhs) -> bool` 1.0.0[src]

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

#### `#[must_use]fn le(&self, other: &Rhs) -> bool` 1.0.0[src]

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

#### `#[must_use]fn gt(&self, other: &Rhs) -> bool` 1.0.0[src]

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

#### `#[must_use]fn ge(&self, other: &Rhs) -> bool` 1.0.0[src]

This method tests greater than or equal to (for `self` and `other`) and is used by the `>=` operator. Read more

### `impl<T: ?Sized, A> Send for Asc<T, A> where
T: Send + Sync,
A: Send + GlobalAlloc,` [src]

### `impl<T: ?Sized, A> Sync for Asc<T, A> where
T: Send + Sync,
A: Sync + GlobalAlloc,` [src]

## Auto Trait Implementations

### `impl<T: ?Sized, A> RefUnwindSafe for Asc<T, A> where
A: RefUnwindSafe,
T: RefUnwindSafe,`

### `impl<T: ?Sized, A> Unpin for Asc<T, A> where
A: Unpin,`

### `impl<T: ?Sized, A> UnwindSafe for Asc<T, A> where
A: UnwindSafe,
T: RefUnwindSafe,`

## Blanket Implementations

### `impl<T> Any for T where
T: 'static + ?Sized,` [src]

#### `pub fn type_id(&self) -> TypeId`[src]

Gets the `TypeId` of `self`. Read more

### `impl<T> Borrow<T> for T where
T: ?Sized,` [src]

#### `pub fn borrow(&self) -> &T`[src]

Immutably borrows from an owned value. Read more

### `impl<T> BorrowMut<T> for T where
T: ?Sized,` [src]

#### `pub fn borrow_mut(&mut self) -> &mut T`[src]

Mutably borrows from an owned value. Read more

### `impl<T> From<!> for T`[src]

#### `pub fn from(t: !) -> T`[src]

Performs the conversion.

### `impl<T> From<T> for T`[src]

#### `pub fn from(t: T) -> T`[src]

Performs the conversion.

### `impl<T, U> Into<U> for T where
U: From<T>,` [src]

#### `pub fn into(self) -> U`[src]

Performs the conversion.

### `impl<T> ToOwned for T where
T: Clone,` [src]

#### `type Owned = T`

The resulting type after obtaining ownership.

#### `pub fn to_owned(&self) -> T`[src]

Creates owned data from borrowed data, usually by cloning. Read more

#### `pub fn clone_into(&self, target: &mut T)`[src]

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

recently added

Uses borrowed data to replace owned data, usually by cloning. Read more

### `impl<T> ToString for T where
T: Display + ?Sized,` [src]

#### `pub default fn to_string(&self) -> String`[src]

Converts the given value to a `String`. Read more

### `impl<T, U> TryFrom<U> for T where
U: Into<T>,` [src]

#### `type Error = Infallible`

The type returned in the event of a conversion error.

#### `pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>`[src]

Performs the conversion.

### `impl<T, U> TryInto<U> for T where
U: TryFrom<T>,` [src]

#### `type Error = <U as TryFrom<T>>::Error`

The type returned in the event of a conversion error.

#### `pub fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>`[src]

Performs the conversion.