Merge branch 'fortran-lang:master' into activations

Author: jalvesz

config/cmake/Findtest-drive.cmake

@@ -123,7 +123,7 @@ foreach(method ${${_pkg}_FIND_METHOD})
 
       # We need the module directory in the subproject before we finish the configure stage
       if(NOT EXISTS "${${_pkg}_BINARY_DIR}/include")
-        make_directory("${${_pkg}_BINARY_DIR}/include")
+        file(MAKE_DIRECTORY "${${_pkg}_BINARY_DIR}/include")
       endif()
 
       break()
@@ -147,7 +147,7 @@ foreach(method ${${_pkg}_FIND_METHOD})
     FetchContent_GetProperties("${_lib}" SOURCE_DIR "${_pkg}_SOURCE_DIR")
     FetchContent_GetProperties("${_lib}" BINARY_DIR "${_pkg}_BINARY_DIR")
     if(NOT EXISTS "${${_pkg}_BINARY_DIR}/include")
-      make_directory("${${_pkg}_BINARY_DIR}/include")
+      file(MAKE_DIRECTORY "${${_pkg}_BINARY_DIR}/include")
     endif()
 
     break()

doc/specs/stdlib_io.md

@@ -17,7 +17,7 @@ Loads a rank-2 `array` from a text file.
 
 ### Syntax
 
-`call ` [[stdlib_io(module):loadtxt(interface)]] `(filename, array [, skiprows] [, max_rows] [, fmt])`
+`call ` [[stdlib_io(module):loadtxt(interface)]] `(filename, array [, skiprows] [, max_rows] [, fmt] [, delimiter])`
 
 ### Arguments
 
@@ -31,7 +31,7 @@ Loads a rank-2 `array` from a text file.
 
 `fmt` (optional): Fortran format specifier for the text read.  Defaults to the write format for the data type.  Setting fmt='*' will specify list directed read.   
 
-
+`delimiter` (optional): Shall be a character expression of length 1 that contains the delimiter used to separate the columns. The default is `' '`.
 
 ### Return value
 
@@ -52,7 +52,8 @@ Experimental
 
 ### Description
 
-Returns the unit number of a file opened to read, to write, or to read and write. The file might be a text file or a binary file. All files are opened using a streamed access.
+Returns the unit number of a file opened to read, to write, or to read and write. The file might be a text file or a binary file.
+Text files are opened using a sequential access, while binary files are opened using a streamed access.
 
 ### Syntax
 
@@ -105,14 +106,16 @@ Saves a rank-2 `array` into a text file.
 
 ### Syntax
 
-`call ` [[stdlib_io(module):savetxt(interface)]] `(filename, array)`
+`call ` [[stdlib_io(module):savetxt(interface)]] `(filename, array [, delimiter])`
 
 ### Arguments
 
 `filename`: Shall be  a character expression containing the name of the file that will contain the 2D `array`.
 
 `array`: Shall be a rank-2 array of type `real`, `complex` or `integer`.
 
+`delimiter` (optional): Shall be a character expression of length 1 that contains the delimiter used to separate the columns. The default is `' '`.
+
 ### Output
 
 Provides a text file called `filename` that contains the rank-2 `array`.

doc/specs/stdlib_math.md

@@ -427,7 +427,7 @@ Experimental
 
 Elemenal function.
 
-### Description
+#### Description
 
 `deg2rad` converts phase angles from degrees to radians.
 

doc/specs/stdlib_sparse.md

@@ -178,7 +178,7 @@ Type-bound procedures to enable requesting data from a sparse matrix.
 
 `v` : Shall be a `real` or `complex` value in accordance to the declared sparse matrix object. If the `ij` tuple is within the sparse pattern, `v` contains the value in the data buffer. If the `ij` tuple is outside the sparse pattern, `v` is equal `0`. If the `ij` tuple is outside the matrix pattern `(nrows,ncols)`, `v` is `NaN`.
 
-## Example
+### Example
 ```fortran
 {!example/linalg/example_sparse_data_accessors.f90!}
 ```
@@ -257,7 +257,7 @@ This module provides facility functions for converting between storage formats.
 
 `chunk`, `optional`: chunk size, only valid in the case of a `SELLC` matrix, by default it will be taken from the `SELLC` default attribute chunk size. It is an `intent(in)` argument.
 
-## Example
+### Example
 ```fortran
 {!example/linalg/example_sparse_from_ijv.f90!}
 ```
@@ -358,7 +358,7 @@ If the `diagonal` array has not been previously allocated, the `diag` subroutine
 
 `coo` : Shall be a `COO` type of `real` or `complex` type. It is an `intent(out)` argument.
 
-## Example
+### Example
 ```fortran
 {!example/linalg/example_sparse_spmv.f90!}
 ```

doc/specs/stdlib_system.md

@@ -335,3 +335,160 @@ Returns a `logical` flag: `.true.` if the system is Windows, or `.false.` otherw
 ```fortran
 {!example/system/example_process_1.f90!}
 ```
+
+## `get_runtime_os` - Determine the OS type at runtime
+
+### Status
+
+Experimental
+
+### Description
+
+`get_runtime_os` inspects the runtime environment to identify the current OS type. It evaluates environment variables (`OSTYPE`, `OS`) and checks for specific files associated with known operating systems.
+The supported OS types are `integer, parameter` variables stored in the `stdlib_system` module:
+
+- **Linux** (`OS_LINUX`)
+- **macOS** (`OS_MACOS`)
+- **Windows** (`OS_WINDOWS`)
+- **Cygwin** (`OS_CYGWIN`)
+- **Solaris** (`OS_SOLARIS`)
+- **FreeBSD** (`OS_FREEBSD`)
+- **OpenBSD** (`OS_OPENBSD`)
+
+If the OS cannot be identified, the function returns `OS_UNKNOWN`.
+
+### Syntax
+
+`os = [[stdlib_system(module):get_runtime_os(function)]]()`
+
+### Class
+
+Function
+
+### Arguments
+
+None.
+
+### Return Value
+
+Returns one of the `integer` `OS_*` parameters representing the OS type, from the `stdlib_system` module, or `OS_UNKNOWN` if undetermined.
+
+### Example
+
+```fortran
+{!example/system/example_get_runtime_os.f90!}
+```
+
+---
+
+## `OS_TYPE` - Cached OS type retrieval
+
+### Status
+
+Experimental
+
+### Description
+
+`OS_TYPE` provides a cached result of the `get_runtime_os` function. The OS type is determined during the first invocation and stored in a static variable. 
+Subsequent calls reuse the cached value, making this function highly efficient.
+
+This caching mechanism ensures negligible overhead for repeated calls, unlike `get_runtime_os`, which performs a full runtime inspection.
+
+### Syntax
+
+`os = [[stdlib_system(module):OS_TYPE(function)]]()`
+
+### Class
+
+Function
+
+### Arguments
+
+None.
+
+### Return Value
+
+Returns one of the `integer` `OS_*` parameters representing the OS type, from the `stdlib_system` module, or `OS_UNKNOWN` if undetermined.
+
+### Example
+
+```fortran
+{!example/system/example_os_type.f90!}
+```
+
+---
+
+## `is_directory` - Test if a path is a directory
+
+### Status
+
+Experimental
+
+### Description
+
+This function checks if a specified file system path is a directory. 
+It is designed to work across multiple platforms. On Windows, paths with both forward `/` and backward `\` slashes are accepted.
+
+### Syntax
+
+`result = [[stdlib_io(module):is_directory(function)]] (path)`
+
+### Class
+
+Function
+
+### Arguments
+
+`path`: Shall be a character string containing the file system path to evaluate. It is an `intent(in)` argument.
+
+### Return values
+
+The function returns a `logical` value:
+
+- `.true.` if the path matches an existing directory.
+- `.false.` otherwise, or if the operating system is unsupported.
+
+### Example
+
+```fortran
+{!example/system/example_is_directory.f90!}
+```
+
+---
+
+## `null_device` - Return the null device file path
+
+### Status
+
+Experimental
+
+### Description
+
+This function returns the file path of the null device, which is a special file used to discard any data written to it. 
+It reads as an empty file. The null device's path varies by operating system:
+- On Windows, the null device is represented as `NUL`.
+- On UNIX-like systems (Linux, macOS), the null device is represented as `/dev/null`.
+
+### Syntax
+
+`path = [[stdlib_system(module):null_device(function)]]()`
+
+### Class
+
+Function
+
+### Arguments
+
+None.
+
+### Return Value
+
+- **Type:** `character(:), allocatable`
+- Returns the null device file path as a character string, appropriate for the operating system.
+
+### Example
+
+```fortran
+{!example/system/example_null_device.f90!}
+```
+

example/io/example.csv

@@ -0,0 +1,3 @@
+ 1.00000000E+00, 1.00000000E+00
+ 1.00000000E+00, 1.00000000E+00
+ 1.00000000E+00, 1.00000000E+00

example/io/example_loadtxt.f90

@@ -6,4 +6,7 @@ program example_loadtxt
 
   ! Can also use list directed format if the default read fails.
   call loadtxt('example.dat', x, fmt='*')
+
+  call loadtxt('example.csv', x, delimiter=',')
+
 end program example_loadtxt

example/io/example_savetxt.f90

@@ -3,4 +3,5 @@ program example_savetxt
   implicit none
   real :: x(3, 2) = 1
   call savetxt('example.dat', x)
+  call savetxt('example.csv', x, delimiter=',')
 end program example_savetxt

example/system/CMakeLists.txt

@@ -1,3 +1,7 @@
+ADD_EXAMPLE(get_runtime_os)
+ADD_EXAMPLE(is_directory)
+ADD_EXAMPLE(null_device)
+ADD_EXAMPLE(os_type)
 ADD_EXAMPLE(process_1)
 ADD_EXAMPLE(process_2)
 ADD_EXAMPLE(process_3)

example/system/example_get_runtime_os.f90

@@ -0,0 +1,9 @@
+! Demonstrate usage of (non-cached) runtime OS query
+program example_get_runtime_os
+    use stdlib_system, only: OS_NAME, get_runtime_os
+    implicit none
+
+    ! Runtime OS detection (full inspection)
+    print *, "Runtime OS Type: ", OS_NAME(get_runtime_os())
+
+end program example_get_runtime_os

example/system/example_is_directory.f90

@@ -0,0 +1,11 @@
+! Demonstrate usage of `is_directory`
+program example_is_directory
+  use stdlib_system, only: is_directory
+  implicit none
+  ! Test a directory path
+  if (is_directory("/path/to/check")) then 
+    print *, "The specified path is a directory."
+  else
+    print *, "The specified path is not a directory."
+  end if
+end program example_is_directory

example/system/example_null_device.f90

@@ -0,0 +1,20 @@
+! Showcase usage of the null device
+program example_null_device
+    use stdlib_system, only: null_device
+    use iso_fortran_env, only: output_unit
+    implicit none
+    integer :: unit 
+    logical :: screen_output = .false.
+
+    if (screen_output) then 
+       unit = output_unit
+    else
+       ! Write to the null device if no screen output is wanted
+       open(newunit=unit,file=null_device())
+    endif     
+
+    write(unit,*) "Hello, world!" 
+
+    if (.not.screen_output) close(unit) 
+
+end program example_null_device

example/system/example_os_type.f90

@@ -0,0 +1,12 @@
+! Demonstrate OS detection
+program example_os_type
+    use stdlib_system, only: OS_TYPE, OS_NAME
+    implicit none
+
+    integer :: current_os
+
+    ! Cached OS detection
+    current_os = OS_TYPE() 
+    print *, "Current OS Type: ", OS_NAME(current_os) 
+
+end program example_os_type

src/CMakeLists.txt

@@ -146,7 +146,7 @@ set(LIB_MOD_DIR ${CMAKE_CURRENT_BINARY_DIR}/mod_files/)
 # We need the module directory before we finish the configure stage since the
 # build interface might resolve before the module directory is generated by CMake
 if(NOT EXISTS "${LIB_MOD_DIR}")
-  make_directory("${LIB_MOD_DIR}")
+  file(MAKE_DIRECTORY "${LIB_MOD_DIR}")
 endif()
 
 set_target_properties(${PROJECT_NAME} PROPERTIES

src/stdlib_constants.fypp

@@ -40,7 +40,7 @@ module stdlib_constants
     real(dp), parameter, public :: epsilon_0 = VACUUM_ELECTRIC_PERMITTIVITY%value !! vacuum mag. permeability
     real(dp), parameter, public :: h = PLANCK_CONSTANT%value !! Planck constant
     real(dp), parameter, public :: Planck = PLANCK_CONSTANT%value !! Planck constant
-    real(dp), parameter, public :: hbar = PLANCK_CONSTANT%value / PI_dp !! Reduced Planck constant
+    real(dp), parameter, public :: hbar = PLANCK_CONSTANT%value / (2.0_dp * PI_dp) !! Reduced Planck constant
     real(dp), parameter, public :: G = NEWTONIAN_CONSTANT_OF_GRAVITATION%value !! Newtonian constant of gravitation
     real(dp), parameter, public :: gravitation_constant = NEWTONIAN_CONSTANT_OF_GRAVITATION%value !! Newtonian constant of gravitation
     real(dp), parameter, public :: g2 = STANDARD_ACCELERATION_OF_GRAVITY%value !! Standard acceleration of gravity