Struct candid::types::principal::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:

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

Similarly, serialization using serde has two versions: serilizing to a byte bufer for non-human readable serializer, and a string version for human readable serializers.

use serde::{Deserialize, Serialize};
use std::str::FromStr;

#[derive(Serialize)]
struct Data {
    id: Principal,
}

let id = Principal::from_str("2chl6-4hpzw-vqaaa-aaaaa-c").unwrap();

// JSON is human readable, so this will serialize to a textual
// representation of the Principal.
assert_eq!(
    serde_json::to_string(&Data { id: id.clone() }).unwrap(),
    r#"{"id":"2chl6-4hpzw-vqaaa-aaaaa-c"}"#
);

// CBOR is not human readable, so will serialize to bytes.
assert_eq!(
    serde_cbor::to_vec(&Data { id: id.clone() }).unwrap(),
    &[161, 98, 105, 100, 73, 239, 205, 171, 0, 0, 0, 0, 0, 1],
);

Implementations

impl Principal

pub const fn management_canister() -> Self

Construct a Principal of the IC management canister

pub fn self_authenticating<P: AsRef<[u8]>>(public_key: P) -> Self

Construct a self-authenticating ID from public key

pub const fn anonymous() -> Self

Construct an anonymous ID.

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

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<Self, PrincipalError>

Construct a Principal from a slice of bytes.

pub fn from_text<S: AsRef<str>>(text: S) -> Result<Self, PrincipalError>

Parse a Principal from text representation.

pub fn to_text(&self) -> String

Convert Principal to text representation.

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

Return the Principal’s underlying slice of bytes.

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 CandidType for Principal

fn id() -> TypeId

fn _ty() -> Type

fn idl_serialize<S>(&self, serializer: S) -> Result<(), S::Error>where
    S: Serializer,

fn ty() -> Type

impl Clone for Principal

fn clone(&self) -> Principal

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Principal

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

Formats the value using the given formatter.

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

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

Deserialize this value from the given Serde deserializer.

impl Display for Principal

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

Formats the value using the given formatter.

impl FromStr for Principal

type Err = PrincipalError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

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

impl Hash for Principal

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 Principal

fn cmp(&self, other: &Principal) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Selfwhere
    Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Selfwhere
    Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Selfwhere
    Self: Sized + PartialOrd<Self>,

Restrict a value to a certain interval.

impl PartialEq<Principal> for Principal

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

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 Serialize for Principal

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

Serialize this value into the given Serde serializer.

impl TryFrom<&[u8]> for Principal

type Error = PrincipalError

The type returned in the event of a conversion error.

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

Performs the conversion.

impl TryFrom<&Vec<u8, Global>> for Principal

type Error = PrincipalError

The type returned in the event of a conversion error.

fn try_from(bytes: &Vec<u8>) -> Result<Self, Self::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<Self, Self::Error>

Performs the conversion.

impl TryFrom<Vec<u8, Global>> for Principal

type Error = PrincipalError

The type returned in the event of a conversion error.

fn try_from(bytes: Vec<u8>) -> Result<Self, Self::Error>

Performs the conversion.

impl Copy for Principal

impl Eq for Principal

impl StructuralEq for Principal

impl StructuralPartialEq for Principal