Skip to content

Latest commit

 

History

History
288 lines (219 loc) · 7.69 KB

Principal.md

File metadata and controls

288 lines (219 loc) · 7.69 KB

base/Principal

Module for interacting with Principals (users, canisters, or other entities).

Principals are used to identify entities that can interact with the Internet Computer including users or canisters.

Example textual representation of Principals:

un4fu-tqaaa-aaaab-qadjq-cai

In Motoko, there is a primitive Principal type called Principal. As an example of where you might see Principals, you can access the Principal of the caller of your shared function.

shared(msg) func foo() {
 let caller : Principal = msg.caller;
};

Then, you can use this module to work with the Principal.

:::note Comparison usage

These functions are defined in this library in addition to the existing comparison operators so that they can be passed as function values to higher-order functions. It is currently not possible to use operators such as ==, !=, <, <=, >, or >= as function values directly. :::

Import from the base library to use this module.

import Principal "mo:base/Principal";

Type Principal

type Principal = Prim.Types.Principal

Function fromActor

func fromActor(a : actor {  }) : Principal

Get the Principal identifier of an actor.

Example:

actor MyCanister {
  func getPrincipal() : Principal {
    let principal = Principal.fromActor(MyCanister);
  }
}

Function toLedgerAccount

func toLedgerAccount(principal : Principal, subAccount : ?Blob) : Blob

Compute the Ledger account identifier of a principal. Optionally specify a sub-account.

Example:

let principal = Principal.fromText("un4fu-tqaaa-aaaab-qadjq-cai");
let subAccount : Blob = "\4A\8D\3F\2B\6E\01\C8\7D\9E\03\B4\56\7C\F8\9A\01\D2\34\56\78\9A\BC\DE\F0\12\34\56\78\9A\BC\DE\F0";
let account = Principal.toLedgerAccount(principal, ?subAccount); // => \8C\5C\20\C6\15\3F\7F\51\E2\0D\0F\0F\B5\08\51\5B\47\65\63\A9\62\B4\A9\91\5F\4F\02\70\8A\ED\4F\82

Function toBlob

func toBlob(p : Principal) : Blob

Convert a Principal to its Blob (bytes) representation.

Example:

let principal = Principal.fromText("un4fu-tqaaa-aaaab-qadjq-cai");
let blob = Principal.toBlob(principal); // => \00\00\00\00\00\30\00\D3\01\01

Function fromBlob

func fromBlob(b : Blob) : Principal

Converts a Blob (bytes) representation of a Principal to a Principal value.

Example:

let blob = "\00\00\00\00\00\30\00\D3\01\01" : Blob;
let principal = Principal.fromBlob(blob);
Principal.toText(principal) // => "un4fu-tqaaa-aaaab-qadjq-cai"

Function toText

func toText(p : Principal) : Text

Converts a Principal to its Text representation.

Example:

let principal = Principal.fromText("un4fu-tqaaa-aaaab-qadjq-cai");
Principal.toText(principal) // => "un4fu-tqaaa-aaaab-qadjq-cai"

Function fromText

func fromText(t : Text) : Principal

Converts a Text representation of a Principal to a Principal value.

Example:

let principal = Principal.fromText("un4fu-tqaaa-aaaab-qadjq-cai");
Principal.toText(principal) // => "un4fu-tqaaa-aaaab-qadjq-cai"

Function isAnonymous

func isAnonymous(p : Principal) : Bool

Checks if the given principal represents an anonymous user.

Example:

let principal = Principal.fromText("un4fu-tqaaa-aaaab-qadjq-cai");
Principal.isAnonymous(principal) // => false

Function isController

func isController(p : Principal) : Bool

Checks if the given principal can control this canister.

Example:

let principal = Principal.fromText("un4fu-tqaaa-aaaab-qadjq-cai");
Principal.isController(principal) // => false

Function hash

func hash(principal : Principal) : Hash.Hash

Hashes the given principal by hashing its Blob representation.

Example:

let principal = Principal.fromText("un4fu-tqaaa-aaaab-qadjq-cai");
Principal.hash(principal) // => 2_742_573_646

Function compare

func compare(principal1 : Principal, principal2 : Principal) : {#less; #equal; #greater}

General purpose comparison function for Principal. Returns the Order ( either #less, #equal, or #greater) of comparing principal1 with principal2.

Example:

let principal1 = Principal.fromText("un4fu-tqaaa-aaaab-qadjq-cai");
let principal2 = Principal.fromText("un4fu-tqaaa-aaaab-qadjq-cai");
Principal.compare(principal1, principal2) // => #equal

Function equal

func equal(principal1 : Principal, principal2 : Principal) : Bool

Equality function for Principal types. This is equivalent to principal1 == principal2.

Example:

let principal1 = Principal.fromText("un4fu-tqaaa-aaaab-qadjq-cai");
let principal2 = Principal.fromText("un4fu-tqaaa-aaaab-qadjq-cai");
ignore Principal.equal(principal1, principal2);
principal1 == principal2 // => true

Example:

import Buffer "mo:base/Buffer";

let buffer1 = Buffer.Buffer<Principal>(3);
let buffer2 = Buffer.Buffer<Principal>(3);
Buffer.equal(buffer1, buffer2, Principal.equal) // => true

Function notEqual

func notEqual(principal1 : Principal, principal2 : Principal) : Bool

Inequality function for Principal types. This is equivalent to principal1 != principal2.

Example:

let principal1 = Principal.fromText("un4fu-tqaaa-aaaab-qadjq-cai");
let principal2 = Principal.fromText("un4fu-tqaaa-aaaab-qadjq-cai");
ignore Principal.notEqual(principal1, principal2);
principal1 != principal2 // => false

Function less

func less(principal1 : Principal, principal2 : Principal) : Bool

"Less than" function for Principal types. This is equivalent to principal1 < principal2.

Example:

let principal1 = Principal.fromText("un4fu-tqaaa-aaaab-qadjq-cai");
let principal2 = Principal.fromText("un4fu-tqaaa-aaaab-qadjq-cai");
ignore Principal.less(principal1, principal2);
principal1 < principal2 // => false

Function lessOrEqual

func lessOrEqual(principal1 : Principal, principal2 : Principal) : Bool

"Less than or equal to" function for Principal types. This is equivalent to principal1 <= principal2.

Example:

let principal1 = Principal.fromText("un4fu-tqaaa-aaaab-qadjq-cai");
let principal2 = Principal.fromText("un4fu-tqaaa-aaaab-qadjq-cai");
ignore Principal.lessOrEqual(principal1, principal2);
principal1 <= principal2 // => true

Function greater

func greater(principal1 : Principal, principal2 : Principal) : Bool

"Greater than" function for Principal types. This is equivalent to principal1 > principal2.

Example:

let principal1 = Principal.fromText("un4fu-tqaaa-aaaab-qadjq-cai");
let principal2 = Principal.fromText("un4fu-tqaaa-aaaab-qadjq-cai");
ignore Principal.greater(principal1, principal2);
principal1 > principal2 // => false

Function greaterOrEqual

func greaterOrEqual(principal1 : Principal, principal2 : Principal) : Bool

"Greater than or equal to" function for Principal types. This is equivalent to principal1 >= principal2.

Example:

let principal1 = Principal.fromText("un4fu-tqaaa-aaaab-qadjq-cai");
let principal2 = Principal.fromText("un4fu-tqaaa-aaaab-qadjq-cai");
ignore Principal.greaterOrEqual(principal1, principal2);
principal1 >= principal2 // => true