Struct kas_core::Id

pub struct Id(/* private fields */);

Widget identifier

All widgets are assigned an identifier which is unique within the window. This type may be tested for equality and order and may be iterated over as a “path” of “key” values.

Formatting an Id via Display prints the the path, for example #1290a4. Here, # represents the root; each following hexadecimal digit represents a path component except that digits 8-f are combined with the following digit(s). Hence, the above path has components 1, 2, 90, a4. To interpret these values, first subtract 8 from each digit but the last digit, then read as base-8: [1, 2, 8, 20].

This type is small (64-bit) and non-zero: Option<Id> has the same size as Id. It is also very cheap to Clone: usually only one if check, and in the worst case a pointer dereference and ref-count increment. Paths up to 14 digits long (as printed) are represented internally; beyond this limit a reference-counted stack allocation is used.

Id is neither Send nor Sync.

Identifiers are assigned when configured and when re-configured (via Action::RECONFIGURE or ConfigCx::configure). In most cases values are persistent but this is not guaranteed (e.g. inserting or removing a child from a List widget will affect the identifiers of all following children). View-widgets assign path components based on the data key, thus possibly making identifiers persistent.

Implementations

impl Id

pub fn is_valid(&self) -> bool

Is the identifier valid?

Default-constructed identifiers are invalid. Comparing invalid ids is considered a logic error and thus will panic in debug builds. This method may be used to check an identifier’s validity.

pub fn iter(&self) -> WidgetPathIter<'_>

Iterate over path components

pub fn path_len(&self) -> usize

Get the path len (number of indices, not storage length)

pub fn is_ancestor_of(&self, id: &Self) -> bool

Returns true if self equals id or if id is a descendant of self

pub fn common_ancestor(&self, id: &Self) -> Self

Find the most-derived common ancestor

pub fn iter_keys_after(&self, id: &Self) -> WidgetPathIter<'_>

pub fn next_key_after(&self, id: &Self) -> Option<usize>

Get first key in path of self path after id

If the path of self starts with the path of id (id.is_ancestor_of(self)) then this returns the next key in self’s path (if any). Otherwise, this returns None.

pub fn parent(&self) -> Option<Id>

Get the parent widget’s identifier, if not root

Note: there is no guarantee that Self::as_u64 on the result will match that of the original parent identifier.

pub fn make_child(&self, key: usize) -> Self

Make an identifier for the child with the given key

Note: this is not a getter method. Calling multiple times with the same key may or may not return the same value!

pub fn as_u64(&self) -> u64

Convert to a u64

This value should not be interpreted, except as follows:

• it is guaranteed non-zero
• it may be passed to Self::opt_from_u64
• comparing two u64 values generated this way will mostly work as an equality check of the source Id, but can return false negatives (only if each id was generated through separate calls to Self::make_child)

pub fn opt_to_u64(id: Option<&Id>) -> u64

Convert Option<Id> to u64

This value should not be interpreted, except as follows:

• it is zero if and only if id == None
• it may be passed to Self::opt_from_u64
• comparing two u64 values generated this way will mostly work as an equality check of the source Id, but can return false negatives (only if each id was generated through separate calls to Self::make_child)

pub unsafe fn opt_from_u64(n: u64) -> Option<Id>

Convert u64 to Option<Id>

Returns None if and only if n == 0.

Safety

This may only be called with the output of Self::as_u64, Self::opt_from_u64, or 0.

This is unsafe since Self has a heap-allocated variant. If n looks like a heap-allocated variant but is not the result of Self::as_u64, or it is but the source instance of Self and all clones have been destroyed, then some operations on the result of this method will attempt to dereference an invalid pointer.

Trait Implementations

impl Clone for Id

fn clone(&self) -> Id

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Id

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

Formats the value using the given formatter.

impl Default for Id

fn default() -> Self

Returns the “default value” for a type.

impl Display for Id

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

Formats the value using the given formatter.

impl HasId for &Id

fn has_id(self) -> Id

impl HasId for &mut Id

fn has_id(self) -> Id

impl HasId for Id

fn has_id(self) -> Id

impl Hash for Id

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 Ord for Id

fn cmp(&self, rhs: &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 + PartialOrd,

Restrict a value to a certain interval.

impl<'a> PartialEq<&'a Id> for Id

fn eq(&self, rhs: &&Id) -> bool

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

fn ne(&self, other: &Rhs) -> bool

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

impl<'a> PartialEq<&'a Option<Id>> for Id

fn eq(&self, rhs: &&Option<Id>) -> bool

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

fn ne(&self, other: &Rhs) -> bool

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

impl PartialEq<&str> for Id

fn eq(&self, rhs: &&str) -> bool

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

fn ne(&self, other: &Rhs) -> bool

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

impl<'a> PartialEq<Option<&'a Id>> for Id

fn eq(&self, rhs: &Option<&'a Id>) -> bool

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

fn ne(&self, other: &Rhs) -> bool

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

impl PartialEq<Option<Id>> for Id

fn eq(&self, rhs: &Option<Id>) -> bool

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

fn ne(&self, other: &Rhs) -> bool

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

impl PartialEq<str> for Id

fn eq(&self, rhs: &str) -> bool

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

fn ne(&self, other: &Rhs) -> bool

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

impl PartialEq for Id

fn eq(&self, rhs: &Self) -> bool

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

fn ne(&self, other: &Rhs) -> bool

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

impl PartialOrd for Id

fn partial_cmp(&self, rhs: &Self) -> Option<Ordering>

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

fn lt(&self, other: &Rhs) -> bool

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

fn le(&self, other: &Rhs) -> bool

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

fn gt(&self, other: &Rhs) -> bool

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

fn ge(&self, other: &Rhs) -> bool

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

impl Eq for Id