Struct Principal 

pub struct Principal { /* private fields */ }

Generic ID on Internet Computer.

Principals are generic identifiers for canisters, users and possibly other concepts in the future. As far as most uses of the IC are concerned they are opaque binary blobs with a length between 0 and 29 bytes, and there is intentionally no mechanism to tell canister ids and user ids apart.

Note a principal is not necessarily tied with a public key-pair, yet we need at least a key-pair of a related principal to sign requests.

A Principal can be serialized to a byte array (Vec<u8>) or a text representation, but the inner structure of the byte representation is kept private.

Example of using a Principal object:

use ic_platform::Principal;

let text = "aaaaa-aa";  // The management canister ID.
let principal = Principal::from_text(text).expect("Could not decode the principal.");
assert!(principal.as_slice().is_empty());
assert_eq!(principal.to_text(), text);

Serialization is always available. It supports serializing to a byte buffer for non-human readable serializer, and a string version for human readable serializers.

Implementations

impl Principal

pub const MAX_LENGTH_IN_BYTES: usize = 29

Maximum significant identity length.

pub const MAX_LENGTH_IN_TEXT: usize = 63

Maximum canonical text length, including dashes and checksum.

pub const fn management_canister() -> Principal

Construct a Principal of the IC management canister

pub fn self_authenticating<P>(public_key: P) -> Principal

where P: AsRef<[u8]>,

Construct a self-authenticating ID from public key

pub const fn anonymous() -> Principal

Construct an anonymous ID.

pub const fn from_slice(slice: &[u8]) -> Principal

Construct a Principal from a slice of bytes.

Panics

Panics if the slice is longer than 29 bytes.

pub const fn try_from_slice(slice: &[u8]) -> Result<Principal, PrincipalError>

Construct a Principal from a slice of bytes.

pub fn from_text<S>(text: S) -> Result<Principal, PrincipalError>

where S: AsRef<str>,

Parse a Principal from text representation.

pub fn to_text(&self) -> String

Convert Principal to text representation.

pub const fn as_slice(&self) -> &[u8]

Returns the Principal’s significant bytes as a slice: the first len bytes of the backing array, without the trailing zero padding.

Use as_fixed_bytes to get the full, fixed-size backing array instead.

pub const fn len(&self) -> u8

Returns the number of significant bytes in the Principal, between 0 and MAX_LENGTH_IN_BYTES inclusive.

This equals the length of the slice returned by as_slice.

pub const fn as_fixed_bytes(&self) -> &[u8; 29]

Returns a reference to the Principal’s fixed-size backing array.

The array is always MAX_LENGTH_IN_BYTES long; bytes from index len onwards are always zero. Prefer as_slice for the significant bytes without padding.

Trait Implementations

impl AsRef<[u8]> for Principal

fn as_ref(&self) -> &[u8]

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

impl Clone for Principal

fn clone(&self) -> Principal

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for Principal

impl Debug for Principal

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Principal

fn deserialize<D>( deserializer: D, ) -> Result<Principal, <D as Deserializer<'de>>::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for Principal

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

Formats the value using the given formatter.

impl Eq for Principal

impl From<Principal> for Principal

fn from(value: Principal) -> Principal

Converts to this type from the input type.

impl FromStr for Principal

type Err = PrincipalError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Principal, <Principal as FromStr>::Err>

Parses a string s to return a value of this type.

impl Hash for Principal

fn hash<__H>(&self, state: &mut __H)

where __H: Hasher,

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 Principal

fn cmp(&self, other: &Principal) -> 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.

fn clamp_to<R>(self, range: R) -> Self

where Self: Sized, R: ClampBounds<Self>,

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

Restrict a value to a certain range.

impl PartialEq for Principal

fn eq(&self, other: &Principal) -> bool

Equality operator ==.

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

Inequality operator !=.

impl PartialOrd for Principal

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

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

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

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

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

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

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

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

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

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

impl Serialize for Principal

fn serialize<S>( &self, serializer: S, ) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Principal

impl TryFrom<&Vec<u8>> for Principal

type Error = PrincipalError

The type returned in the event of a conversion error.

fn try_from( bytes: &Vec<u8>, ) -> Result<Principal, <Principal as TryFrom<&Vec<u8>>>::Error>

Performs the conversion.

impl TryFrom<&[u8]> for Principal

type Error = PrincipalError

The type returned in the event of a conversion error.

fn try_from( bytes: &[u8], ) -> Result<Principal, <Principal as TryFrom<&[u8]>>::Error>

Performs the conversion.

impl TryFrom<&str> for Principal

type Error = PrincipalError

The type returned in the event of a conversion error.

fn try_from(s: &str) -> Result<Principal, <Principal as TryFrom<&str>>::Error>

Performs the conversion.

impl TryFrom<Vec<u8>> for Principal

type Error = PrincipalError

The type returned in the event of a conversion error.

fn try_from( bytes: Vec<u8>, ) -> Result<Principal, <Principal as TryFrom<Vec<u8>>>::Error>

Performs the conversion.