fun save<T: Storable>(_ value: T, to: StoragePath)
The save function saves an object to account storage.
The function moves resources, and copies structures.
If there is already an object stored under the given path, the program aborts.
The path must be a storage path, it must have the domain storage.
T is the type parameter for the object type.
Cadence can infer this type parameter from the argument's type.
The load function loads an object from account storage.
If there is an object stored under the given path,
the function moves the stored resource or structure out of storage
and returns it as an optional.
If there is no object stored under the given path,
the function returns nil.
When the function returns with an object,
the storage no longer stores an object under the given path.
T is the type parameter for the object type.
Programs must explicitly provide a type argument for the parameter.
The type T must be a supertype of the type of the loaded object.
If it is not, the program aborts.
The given type does not necessarily need to be exactly the same as the type of the loaded object.
The path must be a storage path, it must have the domain storage.
view fun copy<T: AnyStruct>(from: StoragePath): T?
The copy function returns a copy of a structure stored in account storage,
without removing it from storage.
If there is a structure stored under the given path,
the function copies the stored structure and returns it as an optional.
If there is no structure stored under the given path,
the function returns nil.
When the function returns with an object,
the structure stays stored in storage after the function returns.
T is the type parameter for the structure type.
Programs must explicitly provide a type argument for the parameter.
The type T must be a supertype of the type of the copied structure.
If it is not, the program aborts.
The given type does not necessarily have to be exactly the same as the type of the copied structure.
The path must be a storage path, it must have the domain storage.
The borrow function returns a reference to an objects stored in storage,
without removing the object from storage.
The function makes it convenient to work with objects in storage
without having to move them out of storage.
If there is a structure stored under the given path,
the function creates a reference to the object and returns the reference as an optional.
If there is no structure stored under the given path,
the function returns nil.
T is the type parameter for the object type.
Programs must explicitly provide a type argument for the parameter.
The type argument must be a reference to any type, &Any (Any is the supertype of all types).
The type T must be a supertype of the type of the borrowed object.
If it is not, the program aborts.
The given type does not necessarily have to be exactly the same as the type of the borrowed object.
The path must be a storage path, it must have the domain storage.
The following functions allow iterating over an account's storage:
fun forEachPublic(_ function: fun(PublicPath, Type): Bool)
fun forEachStored(_ function: fun(StoragePath, Type): Bool)
The functions iterate over all stored objects in the particular domain,
calling the callback function for each stored object,
passing the path and the run-time type of the stored object.
The Bool value returned from the callback function determines whether iteration continues.
If the callback function returns true, iteration proceeds to the next stored object.
If the callback function returns false, the iteration function stops.
The specific order in which the objects are iterated over is undefined,
as is the behavior when a path is added or removed from storage.
info
The iteration functions skip broken objects.
An object could be broken due to invalid types associated with the stored value.
For example, the contract for the stored object might have syntactic or semantic errors.
warning
The order of iteration is undefined. Do not rely on any particular behavior.
Saving an object to a path or loading an object from storage during iteration
can cause the order in which values are stored to change arbitrarily.
When a program continues to iterate after such an operation, the program aborts.
To avoid such errors, do not save objects to storage or load objects from storage during iteration.
If you do perform such an operation,
return false from the iteration callback to cause iteration to end after the mutation like so:
An account's storage is limited by its storage capacity.
An account's storage used is the sum of the size of all the data that the account stores, in MB.
An account's storage capacity is a value that is calculated from the amount of FLOW
that is stored in the account's main FLOW token vault.
At the end of every transaction, the storage used is compared to the storage capacity.
For all accounts involved in the transaction,
if the account's storage used is greater than its storage capacity, the transaction fails.
An account exposes its storage used through the storage.used field,
and its storage capacity through the storage.capacity field.
The fields represent current values:
// Query the storage used before saving an object
let storageUsedBefore = account.storage.used
// Save a resource into storage
account.storage.save(
<-create Counter(count: 123),
to: /storage/counter
)
// Query the storage used again after saving
let storageUsedAfter = account.storage.used
let storageUsedChanged = storageUsedAfter > storageUsedBefore // is true