GTStorable

public protocol GTStorable

It provides standard file operations for types conforming to Codable protocol.

GTStorable protocol provides the following operations:

  • Saving to file.
  • Loading from file.
  • Removing data file.
  • Checking for data file existence.
  • Creating data file backup.
  • Removing data file backup.

Available API

  • save(as:usingOptions:customCoders:)
  • load(from:forObjectOfType:usingOptions:customCoders:)
  • remove(fileOfType:usingOptions:)
  • dataFileExists(ofType:withOptions:)
  • backupDataFile(ofType:usingOptions:)
  • removeBackupFile(ofType:usingOptions:)

See the GTStorableToolkit.FileType enum for supported file types.

Whenever options parameter is required a GTStorableToolkit.StoreOptions can be optionally provided as an argument.

customCoders is an optional GTStorableToolkit.CustomCoders object. Use it to specify customized JSON and Property List encoders and decoders when necessary.

Read more at the documentation of the previously mentioned custom types.

  • save(as:usingOptions:customCoders:) Default implementation

    Undocumented

    Default Implementation

    It saves current instance (self) to file using the specified file type, using optionally additional provided data regarding the path and the file, as well as the encoder to be used.

    Use the fileType parameter to specify the type of file that should be created. See GTStorableToolkit.FileType enum for available values.

    Use the storeOptions parameter to provide additional data regarding the path and the file that will be created. If nil is passed as an argument, the target directory is the documents directory, while the type of the current instance (self type) will be used as the file name. Default extension depends on the specified file type. Override any of those by passing an initialized GTStorableToolkit.StoreOptions argument where you assign values to properties that should be overriden.

    Throws

    It propagates any errors thrown by the system regarding the operations participate in the entire process.

    Declaration

    Swift

    func save(as fileType: GTStorableToolkit.FileType, usingOptions storeOptions: GTStorableToolkit.StoreOptions?, customCoders: GTStorableToolkit.CustomCoders?) throws -> Bool

  • Undocumented

    Default Implementation

    It loads, decodes and returns an object of the given type previously encoded and saved to a file.

    The provided fileType value must match to the file type that was used to save the file. For example, if json file type was used to encode and save, then json should be used again for loading and decoding data from the file. If no custom extension is specified, the file type defines the extension of the file.

    self type is used as the file name to use by default, and the documents directory as the target directory. Provide custom directories, subdirectories, file name and extension by initializing and passing a GTStorableToolkit.StoreOptions object.

    To override default JSON and Property List decoders, initialize a GTStorableToolkit.CustomCoders object with a customized decoder as needed, and pass it as the customCoders argument.

    On success this method initializes an object of the objectType type. It’s a static method so there’s no need to use an instance of the custom type for using it.

    Throws

    It propagates any errors thrown by the system regarding the operations participate in the entire process.

    Declaration

    Swift

    static func load<T>(from fileType: GTStorableToolkit.FileType, forObjectOfType objectType: T.Type, usingOptions storeOptions: GTStorableToolkit.StoreOptions?, customCoders: GTStorableToolkit.CustomCoders?) throws -> T? where T : Decodable
  • remove(fileOfType:usingOptions:) Default implementation

    Undocumented

    Default Implementation

    It removes a previously stored data file of self using the given file type and optionally custom store options.

    Throws

    Any errors thrown by the system while trying to remove the file.

    Declaration

    Swift

    func remove(fileOfType fileType: GTStorableToolkit.FileType, usingOptions storeOptions: GTStorableToolkit.StoreOptions?) throws -> Bool
  • dataFileExists(ofType:withOptions:) Default implementation

    Undocumented

    Default Implementation

    It checks if a data file of self for the given file type and optionally custom store options exists or not.

    Throws

    Any errors thrown by the system while trying to check for file existence.

    Declaration

    Swift

    func dataFileExists(ofType fileType: GTStorableToolkit.FileType, withOptions storeOptions: GTStorableToolkit.StoreOptions?) throws -> Bool
  • backupDataFile(ofType:usingOptions:) Default implementation

    Undocumented

    Default Implementation

    It creates a backup of a data file of self for the given file type and optionally using the given store options.

    The method creates a copy of the data file specified by the file type and appends the bak extension to it. For example, a file named data.json becomes data.json.bak.

    Data files created for different file types can have their own backups. So, data.json.bak can co-exist with data.plist.bak or other supported file types.

    Keep in mind that a backup file overwrites a previous one.

    Warning

    Do not provide a bak extension on your own, it will be appended automatically. Provide only all data necessary to specify the original data file.

    Throws

    Any errors thrown by the system while trying to create the backup file.

    Declaration

    Swift

    func backupDataFile(ofType fileType: GTStorableToolkit.FileType, usingOptions storeOptions: GTStorableToolkit.StoreOptions?) throws -> Bool

  • Undocumented

    Default Implementation

    It deletes a backup file previously created for a data file of self using the given file type, and optionally any given store options.

    Make sure to provide all data necessary to specify the full path to the data file of the specified file type. The method automatically appends the bak extension to the composed path.

    Throws

    Any errors thrown by the system while trying to create the backup file.

    Declaration

    Swift

    func removeBackupFile(ofType fileType: GTStorableToolkit.FileType, usingOptions storeOptions: GTStorableToolkit.StoreOptions?) throws -> Bool