Struct tor_linkspec::ByRelayIds

pub struct ByRelayIds<H: HasRelayIds>
where
    RsaIdentity: Hash + Eq + Clone,
    Ed25519Identity: Hash + Eq + Clone,
{ /* private fields */ }

A set of objects that can be accessed by relay identity.

No more than one object in the set can have any given relay identity.

Invariants

Every object in the set MUST have at least one recognized relay identity; if it does not, it cannot be inserted.

This set may panic or give incorrect results if the values can change their keys through interior mutability.

A set of elements of type H whose members can be accessed by multiple keys.

The keys are: * rsa (RsaIdentity) (Option) * ed25519 (Ed25519Identity) (Option)Each member has a value for each required key, and up to one value for each optional key. The set contains at most one member for any value of a given key.

Requirements

Key types must have consistent Hash and Eq implementations, as they will be used as keys in a HashMap.

If all keys are optional, then every element in this set must have at least one non-None key.

An element must not change its keys over time through interior mutability.

⚠️ If any of these rules is violated, the consequences are unspecified, and could include panics or wrong answers (but not memory-unsafety).

Limitations

This could be more efficient in space and time.

Implementations

impl<H: HasRelayIds> ByRelayIds<H>

where RsaIdentity: Hash + Eq + Clone, Ed25519Identity: Hash + Eq + Clone,

pub fn new() -> Self

Construct a new ByRelayIds

pub fn with_capacity(n: usize) -> Self

Construct a new ByRelayIds with a given capacity.

pub fn by_rsa<BorrowAsKey_>(&self, key: &BorrowAsKey_) -> Option<&H>

where RsaIdentity: Borrow<BorrowAsKey_>, BorrowAsKey_: Hash + Eq + ?Sized,

Return a reference to the element whose rsa is key.

Return None if there is no such element.

pub unsafe fn by_rsa_mut<BorrowAsKey_>( &mut self, key: &BorrowAsKey_ ) -> Option<&mut H>

where RsaIdentity: Borrow<BorrowAsKey_>, BorrowAsKey_: Hash + Eq + ?Sized,

Return a mutable reference to the element whose rsa is key.

Return None if there is no such element.

Safety

This function can put this set into an inconsistent state if the mutable reference is used to change any of the keys. Doing this does not risk Rust safety violations (such as undefined behavior), but it may nonetheless make your program incorrect by causing other functions on this object to panic or give incorrect results.

If you cannot prove to yourself that this won’t happen, then you should use modify_by_* instead.

pub fn contains_rsa<BorrowAsKey_>(&mut self, rsa: &BorrowAsKey_) -> bool

where RsaIdentity: Borrow<BorrowAsKey_>, BorrowAsKey_: Hash + Eq + ?Sized,

Return true if this set contains an element whose rsa is key.

pub fn remove_by_rsa<BorrowAsKey_>(&mut self, rsa: &BorrowAsKey_) -> Option<H>

where RsaIdentity: Borrow<BorrowAsKey_>, BorrowAsKey_: Hash + Eq + ?Sized,

Remove the element whose rsa is key

Return that element on success, and None if there is no such element.“)] rsa

pub fn modify_by_rsa<BorrowAsKey_, F_>( &mut self, rsa: &BorrowAsKey_, func: F_ ) -> Vec<H>

where RsaIdentity: Borrow<BorrowAsKey_>, BorrowAsKey_: Hash + Eq + ?Sized, F_: FnOnce(&mut H),

Modify the element with the given value for rsa by applying func` to it.

func is allowed to change the keys for this value. All indices are updated to refer to the new keys. If the new keys conflict with any previous values, those values are replaced and returned in a vector.

If func causes the value to have no keys at all, then the value itself is also removed and returned in the result vector.

Note that because this function needs to copy all key values and check whether they have changed, it is not terribly efficient.

pub fn by_ed25519<BorrowAsKey_>(&self, key: &BorrowAsKey_) -> Option<&H>

where Ed25519Identity: Borrow<BorrowAsKey_>, BorrowAsKey_: Hash + Eq + ?Sized,

Return a reference to the element whose ed25519 is key.

Return None if there is no such element.

pub unsafe fn by_ed25519_mut<BorrowAsKey_>( &mut self, key: &BorrowAsKey_ ) -> Option<&mut H>

where Ed25519Identity: Borrow<BorrowAsKey_>, BorrowAsKey_: Hash + Eq + ?Sized,

Return a mutable reference to the element whose ed25519 is key.

Return None if there is no such element.

Safety

This function can put this set into an inconsistent state if the mutable reference is used to change any of the keys. Doing this does not risk Rust safety violations (such as undefined behavior), but it may nonetheless make your program incorrect by causing other functions on this object to panic or give incorrect results.

If you cannot prove to yourself that this won’t happen, then you should use modify_by_* instead.

pub fn contains_ed25519<BorrowAsKey_>(&mut self, ed25519: &BorrowAsKey_) -> bool

where Ed25519Identity: Borrow<BorrowAsKey_>, BorrowAsKey_: Hash + Eq + ?Sized,

Return true if this set contains an element whose ed25519 is key.

pub fn remove_by_ed25519<BorrowAsKey_>( &mut self, ed25519: &BorrowAsKey_ ) -> Option<H>

where Ed25519Identity: Borrow<BorrowAsKey_>, BorrowAsKey_: Hash + Eq + ?Sized,

Remove the element whose ed25519 is key

Return that element on success, and None if there is no such element.“)] ed25519

pub fn modify_by_ed25519<BorrowAsKey_, F_>( &mut self, ed25519: &BorrowAsKey_, func: F_ ) -> Vec<H>

where Ed25519Identity: Borrow<BorrowAsKey_>, BorrowAsKey_: Hash + Eq + ?Sized, F_: FnOnce(&mut H),

Modify the element with the given value for ed25519 by applying func` to it.

func is allowed to change the keys for this value. All indices are updated to refer to the new keys. If the new keys conflict with any previous values, those values are replaced and returned in a vector.

If func causes the value to have no keys at all, then the value itself is also removed and returned in the result vector.

Note that because this function needs to copy all key values and check whether they have changed, it is not terribly efficient.

pub fn values(&self) -> impl Iterator<Item = &H> + '_

Return an iterator over the elements in this container.

pub fn into_values(self) -> impl Iterator<Item = H>

Consumer this container and return an iterator of its values.

pub fn try_insert(&mut self, value: H) -> Result<Vec<H>, Error>

Try to insert the value value.

Remove any previous values that shared any keys with value, and return them in a vector on success.

Return Err(Error::NoKeys) if all the keys are optional, and value has no keys at all.

pub fn insert(&mut self, value: H) -> Vec<H>

Try to insert the value value.

Remove any previous values that shared any keys with value, and return them in a vector.

Panics

Panics if all the keys are optional, and value has no keys at all.

pub fn len(&self) -> usize

Return the number of elements in this container.

pub fn is_empty(&self) -> bool

Return true if there are no elements in this container.

pub fn capacity(&self) -> usize

Return the number of elements for which this container has allocated storage.

pub fn retain<F>(&mut self, pred: F)

where F: FnMut(&H) -> bool,

Remove every element that does not satisfy the predicate pred.

pub fn check_invariants(&self)

Assert that this set appears to be in an internally consistent state.

This method can be somewhat expensive, and it should never fail unless your code has a bug.

Panics

Panics if it finds bugs in this object, or constraint violations in its elements. See the (type documentation)Self for a list of constraints.

impl<H: HasRelayIds> ByRelayIds<H>

pub fn by_id<'a, T>(&self, key: T) -> Option<&H>

where T: Into<RelayIdRef<'a>>,

Return the value in this set (if any) that has the key key.

pub fn remove_by_id<'a, T>(&mut self, key: T) -> Option<H>

where T: Into<RelayIdRef<'a>>,

Return the value in this set (if any) that has the key key.

pub fn modify_by_id<'a, T, F>(&mut self, key: T, func: F) -> Vec<H>

where T: Into<RelayIdRef<'a>>, F: FnOnce(&mut H),

Modify the value in this set (if any) that has the key key.

Return values are as for modify_by_ed25519

pub fn by_all_ids<T>(&self, key: &T) -> Option<&H>

where T: HasRelayIds,

Return the value in this set (if any) that has all the relay IDs that key does.

Return None if key has no relay IDs.

pub fn modify_by_all_ids<T, F>(&mut self, key: &T, func: F) -> Vec<H>

where T: HasRelayIds, F: FnOnce(&mut H),

Modify the value in this set (if any) that has all the relay IDs that key does.

Return values are as for modify_by_ed25519

pub fn remove_exact<T>(&mut self, key: &T) -> Option<H>

where T: HasRelayIds,

Remove the single value in this set (if any) that has exactly the same relay IDs that key does

pub fn remove_by_all_ids<T>(&mut self, key: &T) -> Option<H>

where T: HasRelayIds,

Remove the single value in this set (if any) that has all the same relay IDs that key does.

pub fn all_overlapping<T>(&self, key: &T) -> Vec<&H>

where T: HasRelayIds,

Return a reference to every element in this set that shares any ID with key.

No element is returned more than once.

Trait Implementations

impl<H: Clone + HasRelayIds> Clone for ByRelayIds<H>

where RsaIdentity: Hash + Eq + Clone, Ed25519Identity: Hash + Eq + Clone,

fn clone(&self) -> ByRelayIds<H>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<H: Debug + HasRelayIds> Debug for ByRelayIds<H>

where RsaIdentity: Hash + Eq + Clone, Ed25519Identity: Hash + Eq + Clone,

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

Formats the value using the given formatter.

impl<H: HasRelayIds> Default for ByRelayIds<H>

where RsaIdentity: Hash + Eq + Clone, Ed25519Identity: Hash + Eq + Clone,

fn default() -> Self

Returns the “default value” for a type.

impl<H: HasRelayIds> FromIterator<H> for ByRelayIds<H>

where RsaIdentity: Hash + Eq + Clone, Ed25519Identity: Hash + Eq + Clone,

fn from_iter<IntoIter_>(iter: IntoIter_) -> Self

where IntoIter_: IntoIterator<Item = H>,

Creates a value from an iterator.