Handle npz files

.github/workflows/ci_windows.yml

@@ -35,6 +35,8 @@ jobs:
           mingw-w64-${{ matrix.arch }}-python-fypp
           mingw-w64-${{ matrix.arch }}-cmake
           mingw-w64-${{ matrix.arch }}-ninja
+          unzip
+          zip
 
     - run: >-
         PATH=$PATH:/mingw64/bin/ cmake

doc/specs/stdlib_array.md

@@ -10,8 +10,58 @@ title: array
 
 Module for index manipulation and array handling tasks.
 
-## Procedures and methods provided
+## Derived types provided
+
+### `array_wrapper_type`
+
+A derived type that wraps a polymorphic `array_type` and helps with its allocation. By loading an npz file with `load_npz`, a list of array wrappers will be obtained. On the other hand, a list of array wrappers can be saved to an npz file using `save_npz`. Use `add_array` to add an array to a list of array wrappers and call `get_values` on the array wrapper to obtain the values of the underlying array.
+
+#### Status
+
+Experimental
+
+#### Example
+
+```fortran
+program npz_example
+    use stdlib_array, only: array_wrapper_type, add_array
+    use stdlib_io_np, only: save_npz, load_npz
+    implicit none
 
+    type(array_wrapper_type), allocatable :: input_arrays(:), output_arrays(:)
+    real :: x(3, 2) = 1
+    integer :: y(2, 3) = 2
+    real, allocatable :: x_out(:,:)
+    integer, allocatable :: y_out(:,:)
+
+    call add_array(input_arrays, x)
+    call add_array(input_arrays, y)
+
+    call save_npz('example_save.npz', input_arrays)
+
+    call load_npz('example_save.npz', output_arrays)
+
+    if (size(input_arrays) /= 2) then
+        print *, 'Error: Output array has unexpected size.'; stop
+    end if
+
+    call output_arrays(1)%get_values(x_out)
+    call output_arrays(2)%get_values(y_out)
+
+    print *, x_out
+    print *, y_out
+end
+```
+
+### `array_type`
+
+An abstract type that can be extended according to the type and rank of the stored array. It is usually not necessary to interact with this type directly. It is used to store multiple arrays of different types and ranks in a single array.
+
+#### Status
+
+Experimental
+
+## Procedures and methods provided
 
 ### `trueloc`
 
@@ -49,7 +99,6 @@ Returns an array of default integer size, with a maximum length of `size(array)`
 {!example/array/example_trueloc.f90!}
 ```
 
-
 ### `falseloc`
 
 #### Status
@@ -85,3 +134,73 @@ Returns an array of default integer size, with a maximum length of `size(array)`
 ```fortran
 {!example/array/example_falseloc.f90!}
 ```
+
+### `add_array`
+
+#### Status
+
+Experimental
+
+#### Description
+
+Add an array of defined type and rank to a list of array wrappers.
+
+#### Syntax
+
+`call ` [[stdlib_array(module):add_array(interface)]] `(arrays, array[, stat, msg, name])`
+
+#### Class
+
+Pure subroutine.
+
+#### Arguments
+
+`arrays`: List of array wrappers of type `array_wrapper_type` to add `array` to. This argument is `intent(inout)`.
+
+`array`: Array with defined type and rank to be added to the list of array wrappers. This argument is `intent(in)`.
+
+`stat`: Status variable of type `integer`. This argument is `optional` and `intent(out)`. The operation is successful if `stat` is `0`.
+
+`msg`: Error message. This argument is `optional` and `intent(out)`.
+
+`name`: Name of the array. This argument is `optional` and `intent(in)`. If not provided, the name will be set to the default value.
+
+#### Examples
+
+```fortran
+{!example/io/example_save_npz.f90!}
+```
+
+### `get_values`
+
+#### Status
+
+Experimental
+
+#### Description
+
+Get the values of the array within the array wrapper.
+
+#### Syntax
+
+`call ` [[stdlib_array(module):array_wrapper_type(type)]] `%` [[array_wrapper_type(type):get_values(bound)]] `(wrapper, values[, stat, msg])`
+
+#### Class
+
+Pure subroutine.
+
+#### Arguments
+
+`wrapper`: Array wrapper of type `array_wrapper_type` to get the values from. This argument is `intent(in)`.
+
+`values`: Array of the same type and rank as the array within the array wrapper. This argument is `intent(out)`.
+
+`stat`: Status variable of type `integer`. This argument is `optional` and `intent(out)`. The operation is successful if `stat` is `0`.
+
+`msg`: Error message. This argument is `optional` and `intent(out)`.
+
+#### Examples
+
+```fortran
+{!example/io/example_load_npz.f90!}
+```

doc/specs/stdlib_io.md

@@ -136,11 +136,11 @@ Loads an `array` from a npy formatted binary file.
 
 ### Syntax
 
-`call ` [[stdlib_io_npy(module):load_npy(interface)]] `(filename, array[, iostat][, iomsg])`
+`call ` [[stdlib_io_np(module):load_npy(interface)]] `(filename, array[, iostat][, iomsg])`
 
 ### Arguments
 
-`filename`: Shall be  a character expression containing the file name from which to load the `array`.
+`filename`: Shall be a character expression containing the file name from which to load the `array`.
             This argument is `intent(in)`.
 
 `array`: Shall be an allocatable array of any rank of type `real`, `complex` or `integer`.
@@ -164,7 +164,6 @@ Returns an allocated `array` with the content of `filename` in case of success.
 {!example/io/example_loadnpy.f90!}
 ```
 
-
 ## `save_npy`
 
 ### Status
@@ -177,7 +176,7 @@ Saves an `array` into a npy formatted binary file.
 
 ### Syntax
 
-`call ` [[stdlib_io_npy(module):save_npy(interface)]] `(filename, array[, iostat][, iomsg])`
+`call ` [[stdlib_io_np(module):save_npy(interface)]] `(filename, array[, iostat][, iomsg])`
 
 ### Arguments
 
@@ -205,6 +204,70 @@ Provides a npy file called `filename` that contains the rank-2 `array`.
 {!example/io/example_savenpy.f90!}
 ```
 
+## `load_npz`
+
+### Status
+
+Experimental
+
+### Description
+
+Populates an array of `array_wrapper_type` with the contents of an npz file.
+
+### Syntax
+
+`call ` [[stdlib_io_np(module):load_npz(interface)]] `(filename, arrays[, iostat][, iomsg][, tmp_dir])`
+
+### Arguments
+
+`filename`: Shall be a character expression containing the name of the npz file to load from. The argument is `intent(in)`.
+
+`arrays`: Shall be an allocatable array of type `array_wrapper_type` to load the content of the npz file to. This argument is `intent(out)`.
+
+`iostat`: Default integer, contains status of loading to file, zero in case of success. This argument is `optional` and `intent(out)`.
+
+`iomsg`: Deferred length character value, contains error message in case `iostat` is non-zero. It is an optional argument, error message will be dropped if not present. This argument is `intent(out)`.
+
+`tmp_dir`: Shall be a character expression containing the name of the temporary directory to extract the npz file to. The argument is `optional` and `intent(in)`.
+
+### Example
+
+```fortran
+{!example/io/example_load_npz.f90!}
+```
+
+## `save_npz`
+
+### Status
+
+Experimental
+
+### Description
+
+Saves an array of `array_wrapper_type` into a npz file.
+
+### Syntax
+
+`call ` [[stdlib_io_np(module):save_npz(interface)]] `(filename, arrays[, iostat][, iomsg][, compressed])`
+
+### Arguments
+
+`filename`: Shall be a character expression containing the name of the file that contains the arrays. This argument is `intent(in)`.
+
+`arrays`: Shall be arrays of type `array_wrapper_type` that are meant to be saved to disk. This argument is `intent(in)`.
+
+`iostat`: Default integer, contains status of saving to file, zero in case of success. This argument is `optional` and `intent(out)`.
+
+`iomsg`: Deferred length character value, contains error message in case `iostat` is non-zero. It is an optional argument, error message will be dropped if not present. This argument is `intent(out)`.
+
+`compressed`: Shall be a logical expression that determines if the npz file should be compressed. The argument is `optional` and `intent(in)`. The default value is `.false.`.
+
+### Example
+
+```fortran
+{!example/io/example_save_npz.f90!}
+```
+
 ## `getline`
 
 ### Status
@@ -260,3 +323,117 @@ Provides formats for all kinds as defined in the `stdlib_kinds` module.
 ```fortran
 {!example/io/example_fmt_constants.f90!}
 ```
+
+## `zip`
+
+### Status
+
+Experimental
+
+### Description
+
+Compresses a file or directory into a zip archive.
+
+### Syntax
+
+`call ` [[stdlib_io_zip(module):zip(subroutine)]] ` (output_file, files[, stat][, msg][, compressed])`
+
+### Arguments
+
+`output_file`: Character expression representing the name of the zip file to create. This argument is `intent(in)`.
+
+`files`: Array of `string_type` representing the names of the files to compress. This argument is `intent(in)`.
+
+`stat`: Default integer, contains status of reading from unit, zero in case of success. This argument is `optional` and `intent(out)`.
+
+`msg`: Deferred length character value, contains error message in case `iostat` is non-zero. It is an `optional` argument, error message will be dropped if not present. This argument is `intent(out)`.
+
+`compressed`: Logical expression that determines if the zip file should be compressed. The argument is `optional` and `intent(in)`. The default value is `.true.`.
+
+## `unzip`
+
+### Status
+
+Experimental
+
+### Description
+
+Extracts a zip archive into a directory.
+
+### Syntax
+
+`call ` [[stdlib_io_zip(module):unzip(subroutine)]] ` (filename, outputdir[, stat][, msg])`
+
+### Arguments
+
+`filename`: Character expression representing the name of the zip file to extract. This argument is `intent(in)`.
+
+`outputdir`: Character expression representing the name of the directory to extract the zip file to. This argument is `intent(in)`.
+
+`stat`: Default integer, contains status of reading from unit, zero in case of success. This argument is `optional` and `intent(out)`.
+
+`msg`: Deferred length character value, contains error message in case `iostat` is non-zero. It is an `optional` argument, error message will be dropped if not present. This argument is `intent(out)`.
+
+## `exists`
+
+### Status
+
+Experimental
+
+### Description
+
+Whether a file or directory exists at the given location in the filesystem.
+
+### Syntax
+
+`is_existing = ` [[stdlib_io_filesystem(module):exists(function)]] ` (filename)`
+
+### Arguments
+
+`filename`: Character expression representing the name of the file or directory to check for existence. This argument is `intent(in)`.
+
+## `list_dir`
+
+### Status
+
+Experimental
+
+### Description
+
+Lists the contents of a directory.
+
+### Syntax
+
+`call ` [[stdlib_io_filesystem(module):list_dir(subroutine)]] ` (dir, files[, iostat][, iomsg])`
+
+### Arguments
+
+`dir`: Character expression representing the name of the directory to list. This argument is `intent(in)`.
+
+`files`: Array of `string_type` representing the names of the files in the directory. This argument is `intent(out)`.
+
+`iostat`: Default integer, contains status of reading from unit, zero in case of success. This argument is `optional` and `intent(out)`.
+
+`iomsg`: Deferred length character value, contains error message in case `iostat` is non-zero. It is an `optional` argument, error message will be dropped if not present. This argument is `intent(out)`.
+
+## `run`
+
+### Status
+
+Experimental
+
+### Description
+
+Runs a command in the shell.
+
+### Syntax
+
+`call ` [[stdlib_io_filesystem(module):run(subroutine)]] ` (command[, iostat][, iomsg])`
+
+### Arguments
+
+`command`: Character expression representing the command to run. This argument is `intent(in)`.
+
+`iostat`: Default integer, contains status of reading from unit, zero in case of success. This argument is `optional` and `intent(out)`.
+
+`iomsg`: Deferred length character value, contains error message in case `iostat` is non-zero. It is an `optional` argument, error message will be dropped if not present. This argument is `intent(out)`.

example/io/CMakeLists.txt

@@ -5,3 +5,5 @@ ADD_EXAMPLE(loadtxt)
 ADD_EXAMPLE(open)
 ADD_EXAMPLE(savenpy)
 ADD_EXAMPLE(savetxt)
+ADD_EXAMPLE(load_npz)
+ADD_EXAMPLE(save_npz)

example/io/example_load_npz.f90

@@ -0,0 +1,18 @@
+program example_load_npz
+    use stdlib_array, only: array_wrapper_type
+    use stdlib_kinds, only: int32, sp
+    use stdlib_io_np, only: load_npz
+    implicit none
+
+    type(array_wrapper_type), allocatable :: arrays(:)
+    real(sp), allocatable :: array_1(:,:)
+    integer(int32), allocatable :: array_2(:,:)
+
+    call load_npz('example_load.npz', arrays)
+
+    call arrays(1)%get_values(array_1)
+    call arrays(2)%get_values(array_2)
+
+    print *, array_1
+    print *, array_2
+end