Candid support for the candy values.
3 |public func value_to_candid(val : Types.CandyShared) : [Arg.Arg]Convert a CandyShared to an Array of Candid Arg.
Example:
5 |motoko include=import
6 | let val: CandyShared = #Option(?#Principal(Principal.fromText("xyz")));
7 | let candid = Candid.value_to_candid(val);Cloning support for the candy values.
3 |This module contains a few utilities for deep cloning candy values.
4 |JSON support for the candy library.
3 |This module contains the utilities useful for handling JSON values.
4 |public func value_to_json(val : Types.CandyShared) : TextConvert CandyShared to JSON format as Text.
Example:
6 |motoko include=import
7 | let val: CandyShared = #Option(?#Principal(Principal.fromText("xyz")));
8 | let val_as_json = Json.value_to_json(val);Upgrade utilities for the candy library.
3 |This module contains the utility functions to upgrade candy values from version 1 to version 2.
4 |public func upgradeCandy(item : CandyOld.CandyValueUnstable) : CandyTypes.CandyUpgrade from V1 representation of CandyShared to the V2 representation.
public func upgradeCandyShared(item : CandyOld.CandyValue) : CandyTypes.CandySharedUpgrade from V1 representation of CandySharedUnstable to the V2 representation 'CandyValudShared'.
Hexadecimal support for the candy library.
3 |This module contains the utilities useful for handling hexadecimal values.
4 |Defines a type to indicate that the decoder has failed.
5 |public func encode(array : [Nat8]) : TextEncode an array of unsigned 8-bit integers in hexadecimal format.
6 |public func decode(text : Text) : Result<[Nat8], DecodeError>Decode an array of unsigned 8-bit integers in hexadecimal format.
7 |Returns a DecodeError if the decoding is unsuccessful.
8 |Cloning support for the candy values.
4 |This module contains a few utilities for deep cloning candy values.
5 |Conversion utilities for the candy library.
6 |This module contains the conversion functions to convert values to & from 7 | candy values.
8 |Hexadecimal support for the candy library.
9 |This module contains the utilities useful for handling hexadecimal values.
10 |JSON support for the candy library.
11 |This module contains the utilities useful for handling JSON values.
12 |Properties for the candy library.
13 |This module contains the properties and class functions for updating and 14 | manipulating classes.
15 |Types for the candy library.
16 |This module contains the types that denote candy values, properties 17 | and workspace. 18 | It also contains a few converstion functions to serialize/deserialize 19 | & stabilize/destabilize candy values.
20 |Upgrade utilities for the candy library.
21 |This module contains the utility functions to upgrade candy values from version 1 to version 2.
22 |Workspace utilities for the candy library.
23 |This module contains the utilities useful for keeping workable data in 24 | chunks that can be moved around canisters. They enable the inspection and 25 | manipulation of workspaces.
26 |Properties for the candy library.
3 |This module contains the properties and class functions for updating and 4 | manipulating classes.
5 |public func getPropertiesShared(properties : PropertiesShared, qs : [Query]) : Result.Result<PropertiesShared, PropertySharedError>Get a subset of fields from the PropertiesShared based on the given query.
Example:
7 |motoko include=import
8 | let properties: PropertiesShared = [
9 | {
10 | name = "prop1";
11 | value = #Principal(Principal.fromText("abc"));
12 | immutable = false;
13 | },
14 | {
15 | name = "prop2";
16 | value = #Nat8(44);
17 | immutable = true;
18 | },
19 | {
20 | name = "prop3";
21 | value = #Class(
22 | {
23 | name = "class_field1";
24 | value = #Nat(222);
25 | immutable = false;
26 | },
27 | {
28 | name = "class_field2";
29 | value = #Text("sample");
30 | immutable = true;
31 | }
32 | );
33 | immutable = false;
34 | }
35 | ];
36 | let qs = [
37 | {
38 | name = "prop2"
39 | },
40 | {
41 | name = "prop3";
42 | next = [
43 | {
44 | name = "class_field2";
45 | }
46 | ];
47 | }
48 | ];
49 | // Will return prop2 and the class_field2 from prop3.
50 | let subset_result = Properties.getPropertiesShared(properties, qs);Note: Ignores unknown properties.
51 |public func updatePropertiesShared(properties : PropertiesShared, us : [UpdateShared]) : Result.Result<PropertiesShared, PropertySharedError>Updates the given properties based on the given update query.
52 |Example:
53 |motoko include=import
54 | let properties: PropertiesShared = [
55 | {
56 | name = "prop1";
57 | value = #Principal(Principal.fromText("abc"));
58 | immutable = true;
59 | },
60 | {
61 | name = "prop2";
62 | value = #Nat8(44);
63 | immutable = false;
64 | },
65 | {
66 | name = "prop3";
67 | value = #Class(
68 | {
69 | name = "class_field1";
70 | value = #Nat(222);
71 | immutable = false;
72 | },
73 | {
74 | name = "class_field2";
75 | value = #Text("sample");
76 | immutable = true;
77 | }
78 | );
79 | immutable = false;
80 | }
81 | ];
82 | let us = [
83 | {
84 | name = "prop1",
85 | mode = #Set(#Nat8(66))
86 | },
87 | {
88 | name = "prop3";
89 | mode = #Next([
90 | {
91 | name = "class_field1";
92 | mode = #Lock(#Nat(333));
93 | }
94 | ])
95 | }
96 | ];
97 | // Will update prop1 and the class_field1 from prop3 to new values.
98 | let updated_properties = Properties.updatePropertiesShared(properties, us);Note:
99 |public func getClassPropertyShared(val : CandyShared, name : Text) : ?PropertySharedUpdates the given properties based on the given update query.
100 |Example:
101 |motoko include=import
102 | let c = #Class(
103 | {
104 | name = "class_field1";
105 | value = #Nat(222);
106 | immutable = false;
107 | },
108 | {
109 | name = "class_field2";
110 | value = #Text("sample");
111 | immutable = true;
112 | }
113 | );
114 | let prop = Properties.getClassPropertyShared(c, "class_field1");Note: Returns null if:
115 |public func getProperties(properties : Properties, qs : [Query]) : Result.Result<Properties, PropertySharedError>Get a subset of fields from the Properties based on the given query.
Example:
117 |motoko include=import
118 | let properties: Properties = [
119 | {
120 | name = "prop1";
121 | value = #Principal(Principal.fromText("abc"));
122 | immutable = false;
123 | },
124 | {
125 | name = "prop2";
126 | value = #Nat8(44);
127 | immutable = true;
128 | },
129 | {
130 | name = "prop3";
131 | value = #Class(
132 | {
133 | name = "class_field1";
134 | value = #Nat(222);
135 | immutable = false;
136 | },
137 | {
138 | name = "class_field2";
139 | value = #Text("sample");
140 | immutable = true;
141 | }
142 | );
143 | immutable = false;
144 | }
145 | ];
146 | let qs = [
147 | {
148 | name = "prop2"
149 | },
150 | {
151 | name = "prop3";
152 | next = [
153 | {
154 | name = "class_field2";
155 | }
156 | ];
157 | }
158 | ];
159 | // Will return prop2 and the class_field2 from prop3.
160 | let subset_result = Properties.getProperties(properties, qs);Note: Ignores unknown properties.
161 |public func updateProperties(properties : Properties, us : [Update]) : Result.Result<Properties, PropertySharedError>Updates the given properties based on the given update query.
162 |Example:
163 |motoko include=import
164 | let properties: Properties = [
165 | {
166 | name = "prop1";
167 | value = #Principal(Principal.fromText("abc"));
168 | immutable = true;
169 | },
170 | {
171 | name = "prop2";
172 | value = #Nat8(44);
173 | immutable = false;
174 | },
175 | {
176 | name = "prop3";
177 | value = #Class(
178 | {
179 | name = "class_field1";
180 | value = #Nat(222);
181 | immutable = false;
182 | },
183 | {
184 | name = "class_field2";
185 | value = #Text("sample");
186 | immutable = true;
187 | }
188 | );
189 | immutable = false;
190 | }
191 | ];
192 | let us = [
193 | {
194 | name = "prop1",
195 | mode = #Set(#Nat8(66))
196 | },
197 | {
198 | name = "prop3";
199 | mode = #Next([
200 | {
201 | name = "class_field1";
202 | mode = #Lock(#Nat(333));
203 | }
204 | ])
205 | }
206 | ];
207 | // Will update prop1 and the class_field1 from prop3 to new values.
208 | let updated_properties = Properties.updateProperties(properties, us);Note:
209 |Workspace utilities for the candy library.
3 |This module contains the utilities useful for keeping workable data in 4 | chunks that can be moved around canisters. They enable the inspection and 5 | manipulation of workspaces.
6 |public func countAddressedChunksInWorkspace(x : Workspace) : NatGet the count of addressed chunks in the given Workspace.
Example:
8 |motoko include=import
9 | let ws = Workspace.initWorkspace(3);
10 | StableBuffer.add<DataZone>(ws, StableBuffer.initPresized<DataChunk>(1));
11 | StableBuffer.add<DataZone>(ws, StableBuffer.initPresized<DataChunk>(5));
12 | StableBuffer.add<DataZone>(ws, StableBuffer.initPresized<DataChunk>(2));
13 | let count = Workspace.countAddressedChunksInWorkspace(ws); // 8.public func emptyWorkspace() : WorkspaceCreate an empty Workspace.
public func initWorkspace(size : Nat) : WorkspaceInitialize a Workspace with the given capacity.
public func getCandySize(item : Candy) : NatGet the size in bytes taken up by the Candy.
public func getCandySharedSize(item : CandyShared) : NatGet the size in bytes taken up by the CandyShared.
public func workspaceToAddressedChunkArray(x : Workspace) : AddressedChunkArrayConvert Workspace to AddressedChunkArray.
Example:
19 |motoko include=import
20 | let ws = Workspace.initWorkspace(3);
21 | StableBuffer.add<DataZone>(ws, StableBuffer.initPresized<DataChunk>(1));
22 | StableBuffer.add<DataZone>(ws, StableBuffer.initPresized<DataChunk>(5));
23 | StableBuffer.add<DataZone>(ws, StableBuffer.initPresized<DataChunk>(2));
24 | let addressed_chunk_array = Workspace.workspaceToAddressedChunkArray(ws);public func workspaceDeepClone(x : Workspace) : WorkspaceGet a deep clone of the given Workspace.
Example:
26 |motoko include=import
27 | let ws = Workspace.initWorkspace(3);
28 | StableBuffer.add<DataZone>(ws, StableBuffer.initPresized<DataChunk>(1));
29 | StableBuffer.add<DataZone>(ws, StableBuffer.initPresized<DataChunk>(5));
30 | StableBuffer.add<DataZone>(ws, StableBuffer.initPresized<DataChunk>(2));
31 | let ws_clone = Workspace.workspaceDeepClone(ws);public func fromAddressedChunks(x : AddressedChunkArray) : WorkspaceCreate a Workspace from an AddressedChunkArray.
Example:
33 |motoko include=import
34 | let arr: AddressedChunkArray = [(1, 1, #Nat(10)), (8, 4, #Float(3.14))];
35 | let ws = Workspace.fromAddressedChunks(arr);public func fileAddressedChunks(workspace : Workspace, x : AddressedChunkArray)public func getDataZoneSize(dz : DataZone) : NatGet the size in bytes taken up by all values in the DataZone.
public func getWorkspaceChunkSize(_workspace : Workspace, _maxChunkSize : Nat) : NatGet the number of chunks for Workspace when dividing into chunks of size <= _maxChunkSize .
Example:
38 |motoko include=import
39 | let ws = Workspace.initWorkspace(3);
40 | StableBuffer.add<DataZone>(ws, StableBuffer.initPresized<DataChunk>(1));
41 | StableBuffer.add<DataZone>(ws, StableBuffer.initPresized<DataChunk>(5));
42 | StableBuffer.add<DataZone>(ws, StableBuffer.initPresized<DataChunk>(2));
43 | let chunk_size = Workspace.getWorkspaceChunkSize(ws, 2);public func getWorkspaceChunk(
_workspace : Workspace,
_chunkID : Nat,
_maxChunkSize : Nat
) : ({#eof; #chunk}, AddressedChunkBuffer)public func getAddressedChunkArraySize(item : AddressedChunkArray) : NatGet the size of the AddressedChunkArray.
Example:
45 |motoko include=import
46 | let arr: AddressedChunkArray = [(1, 1, #Nat(10)), (8, 4, #Float(3.14))];
47 | let size = Workspace.getAddressedChunkArraySize(arr); // 21Note: This only works for up to 32 bytes addresses.
48 |public func getDataChunkFromAddressedChunkArray(
item : AddressedChunkArray,
dataZone : Nat,
dataChunk : Nat
) : CandySharedGet the data chunk from a AddressedChunkArray at the given zone and chunk.
Example:
50 |motoko include=import
51 | let arr: AddressedChunkArray = [(1, 1, #Nat(10)), (8, 4, #Float(3.14))];
52 | let chunk = Workspace.getDataChunkFromAddressedChunkArray(arr, 8, 4); // #Float(3.14)public func byteBufferDataZoneToBuffer(dz : DataZone) : Buffer.Buffer<Buffer.Buffer<Nat8>>public func byteBufferChunksToCandyBufferDataZone(buffer : Buffer.Buffer<Buffer.Buffer<Nat8>>) : DataZonepublic func flattenAddressedChunkArray(data : AddressedChunkArray) : [Nat8]Flatten an AddressedChunkArray to produce [Nat8].
Example:
55 |motoko include=import
56 | let arr: AddressedChunkArray = [(1, 1, #Nat(10)), (8, 4, #Float(3.14))];
57 | let bytes = Workspace.flattenAddressedChunkArray(arr);Note: Loses integrity after 256 Zones or 256 chunks.
58 |Types for the candy library.
3 |This module contains the types that denote candy values, properties 4 | and workspace. 5 | It also contains a few converstion functions to serialize/deserialize 6 | & stabilize/destabilize candy values.
7 |A collection of Property.
Specifies a single unstable property.
9 |Specifies the unstable properties that should be updated to a certain value.
10 |Update information for a single property.
11 |Mode for the update operation.
12 |Specifies a single property.
13 |A collection of PropertyShared.
Specifies an error which occurred during an operation on a PropertyShared.
Specifies the properties that should be queried.
16 |Mode for the query operation.
17 |Specifies the properties that should be updated to a certain value.
18 |Update information for a single property.
19 |Mode for the update operation.
20 |The Stable CandyShared.
21 |The Shared CandyShared.
22 |Note: A DataChunk should be no larger than 2MB so that it can be shipped to other canisters.
Workspaces are valueble when using orthogonal persistance to keep track of data in a format 24 | that is easily transmitable across the wire given IC restrictions
25 |public func shareCandy(item : Candy) : CandySharedConvert a Candy to CandyShared.
Example:
27 |motoko include=import
28 | let unstable: Candy = #Principal(Principal.fromText("abc"));
29 | let shareCandy = Types.shareCandy(unstable);public func unshare(item : CandyShared) : CandyConvert a CandyShared to Candy.
Example:
31 |motoko include=import
32 | let stable: CandyShared = #Principal(Principal.fromText("abc"));
33 | let unsharedValue = Types.unshare(unstable);public func shareProperty(item : Property) : PropertySharedConvert a Property to PropertyShared.
Example:
35 |motoko include=import
36 | let unstable: Property = {
37 | name = "name";
38 | value = #Principal(Principal.fromText("abc"));
39 | immutable = false;
40 | };
41 | let stablePropertyShared = Types.shareProperty(unstable);public func unshareProperty(item : PropertyShared) : PropertyConvert a PropertyShared to Property.
Example:
43 |motoko include=import
44 | let stablePropertyShared: PropertyShared = {
45 | name = "name";
46 | value = #Principal(Principal.fromText("abc"));
47 | immutable = true;
48 | };
49 | let unstablePropertyShared = Types.unshareProperty(stablePropertyShared);public func shareCandyArray(items : [Candy]) : [CandyShared]Convert a [Candy] to [CandyShared].
Example:
51 |motoko include=import
52 | let array: [Candy] = [#Principal(Principal.fromText("abc")), #Int(1)];
53 | let arrayStable = Types.shareCandyArray(array);public func unshareArray(items : [CandyShared]) : [Candy]Convert a [CandyShared] to [Candy].
Example:
55 |motoko include=import
56 | let arrayStable: [CandyShared] = [#Principal(Principal.fromText("abc")), #Int(1)];
57 | let array = Types.unshareArray(arrayStable);public func shareCandyBuffer(items : DataZone) : [CandyShared]Convert a DataZone to [CandyShared].
Example:
59 |motoko include=import
60 | let dataZone = Types.toBuffer<DataChunk>([#Int32(5), #Int(1)]);
61 | let sharedValues = Types.shareCandyBuffer(dataZone);public func toBuffer<T>(x : [T]) : StableBuffer.StableBuffer<T>Create a Buffer from [T] where T can be of any type.
Example:
63 |motoko include=import
64 | let array = [1, 2, 3];
65 | let buf = Types.toBuffer<Nat>(array); public func hash(x : Candy) : NatGet the hash of the CandyShared.
Example:
67 |motoko include=import
68 | let x: CandyShared = #Principal(Principal.fromText("abc"));
69 | let h = Types.hash(x);public func eq(x : Candy, y : Candy) : BoolChecks the two CandyShared params for equality.
Example:
71 |motoko include=import
72 | let x: CandyShared = #Int(1);
73 | let y: CandyShared = #Int(2);
74 | let z: CandyShared = #Int(1);
75 | let x_y = Types.eq(x, y); // false
76 | let x_z = Types.eq(x, z); // truepublic let candyMapHashTool : public func hashShared(x : CandyShared) : NatGet the hash of the Candy.
Example:
78 |motoko include=import
79 | let x: Candy = #Principal(Principal.fromText("abc"));
80 | let h = Types.hashShared(x); public func eqShared(x : CandyShared, y : CandyShared) : BoolChecks the two CandyShared params for equality.
Example:
82 |motoko include=import
83 | let x: Candy = #Int(1);
84 | let y: Candy = #Int(2);
85 | let z: Candy = #Int(1);
86 | let x_y = Types.eq(x, y); // false
87 | let x_z = Types.eq(x, z); // truepublic let candySharedMapHashTool :
Candid support for the candy values.
3 |