.. _stdlib_local_storage_core:

=============
Local storage
=============

This module is used to save and load local storage under a specific name. It uses the `GenericStorage` class to store data. Users can have multiple storages with different names. The storages are typically used to save game data.

To use this module, include the following line in your project file::

    require engine.local_storage_core // or require engine.core

++++++++++++
Enumerations
++++++++++++

.. _enum-local_storage_core-SaveStorageResult:

.. das:attribute:: SaveStorageResult

The result of saving a storage.

:Values: * **UnableToSave** = 0 - The storage could not be saved. Issue with the storage or the file system.

         * **Success** = 1 - The storage was saved successfully.

         * **FileSizeLimitExceeded** = 2 - The storage was not saved because it exceeded the file size limit (5mb).

         * **LimitExceeded** = 3 - The storage was not saved because it exceeded the global files limit (20 files).


+++++++++
Functions
+++++++++

  *  :ref:`load_storage (name: string; blk: block\<(var data:GenericStorage#):void\>) : bool <function-local_storage_core_load_storage_string_block_ls_var_data_c_GenericStorage_hh__c_void_gr_>` 
  *  :ref:`load_storage (name: string) : GenericStorage <function-local_storage_core_load_storage_string>` 
  *  :ref:`save_storage (var data: GenericStorage|GenericStorage#; name: string = "") : SaveStorageResult <function-local_storage_core_save_storage_GenericStorageGenericStorage_hh__string>` 
  *  :ref:`remove_storage (name: string implicit) : bool <function-public_system_remove_storage_string_implicit>` 

.. _function-local_storage_core_load_storage_string_block_ls_var_data_c_GenericStorage_hh__c_void_gr_:

.. das:function:: load_storage(name: string; blk: block<(var data:GenericStorage#):void>) : bool

Loads the storage with the given name and passes the data to the provided block. Preferred over the other version of `load_storage` because it cleans up the memory after the block is done executing.

:Arguments: * **name** : string -  the name of the storage to load

            * **blk** : block<(data: :ref:`GenericStorage <struct-generic_storage-GenericStorage>` #):void> -  the block to receive the loaded data



:Returns: * bool -  `true` if the data was loaded successfully, `false` otherwise

Usage example::

    load_storage("myStorage") $(var storage : GenericStorage#) {
        let score = get_or(storage, "score", 0)
    }

.. _function-local_storage_core_load_storage_string:

.. das:function:: load_storage(name: string) : GenericStorage

Loads the storage with the given name and returns the data.

:Arguments: * **name** : string -  the name of the storage to load



:Returns: *  :ref:`GenericStorage <struct-generic_storage-GenericStorage>`  -  the loaded data as a `GenericStorage` object, storage will be empty if the data could not be loaded

Usage example::

    var storage = load_storage("myStorage")
    let score = get_or(storage, "score", 0)

.. _function-local_storage_core_save_storage_GenericStorageGenericStorage_hh__string:

.. das:function:: save_storage(data: GenericStorage|GenericStorage#; name: string = "") : SaveStorageResult

Saves the given data to local storage with an optional name.

:Arguments: * **data** : option< :ref:`GenericStorage <struct-generic_storage-GenericStorage>` | :ref:`GenericStorage <struct-generic_storage-GenericStorage>` #> -  the data to be saved

            * **name** : string -  the name of the storage (optional)



:Returns: *  :ref:`SaveStorageResult <enum-local_storage_core-SaveStorageResult>`  -  the result of saving the storage

Usage example::

    var storage : GenericStorage
    set(storage, "score", score)
    save_storage(storage, "myStorage")

.. _function-public_system_remove_storage_string_implicit:

.. das:function:: remove_storage(name: string implicit) : bool

Removes the storage with the given name.

:Arguments: * **name** : string implicit -  the name of the storage to remove



:Returns: * bool -  `true` if the storage was removed successfully, `false` otherwise

Usage example::

    remove_storage("myStorage")