function -> subroutine

Author: perazz

doc/specs/stdlib_io.md

@@ -269,11 +269,11 @@ Experimental
 
 ### Description
 
-This function reads the entirety of a specified ASCII file and returns its content as a string. The function provides an optional error-handling mechanism via the `state_type` class. If the `err` argument is not provided, exceptions will trigger an `error stop`. The function also supports an optional flag to delete the file after reading.
+This subroutine reads the entirety of a specified ASCII file and returns its content as a string. The function provides an optional error-handling mechanism via the `state_type` class. If the `err` argument is not provided, exceptions will trigger an `error stop`. The function also supports an optional flag to delete the file after reading.
 
 ### Syntax
 
-`call [[stdlib_io(module):getfile(function)]] (fileName [, err] [, delete=.false.])`
+`call [[stdlib_io(module):getfile(function)]] (fileName, fileContents [, err] [, delete=.false.])`
 
 ### Class
 Function
@@ -282,13 +282,15 @@ Function
 
 `fileName`: Shall be a character input containing the path to the ASCII file to read. It is an `intent(in)` argument.
 
+`fileContents`: Shall be a `type(string_type)` variable containing the full content of the specified file. It is an `intent(out)` argument.
+ 
 `err` (optional): Shall be a `type(state_type)` variable. It is an `intent(out)` argument used for error handling.
 
 `delete` (optional): Shall be a `logical` flag. If `.true.`, the file is deleted after reading. Default is `.false.`. It is an `intent(in)` argument.
 
 ### Return values
 
-The function returns a `string_type` variable containing the full content of the specified file.
+Output variable `fileContents` will contain the full content of the specified file.
 
 Raises `STDLIB_IO_ERROR` if the file is not found, cannot be opened, read, or deleted. 
 Exceptions trigger an `error stop` unless the optional `err` argument is provided.

example/io/example_getfile.f90

@@ -10,7 +10,7 @@ program example_getfile
   type(state_type) :: err
 
   ! Read a file into a string
-  fileContent = getfile(fileName, err=err)
+  call getfile(fileName, fileContent, err=err)
 
   if (err%error()) then
     print *, err%print()

src/stdlib_io.fypp

@@ -24,11 +24,11 @@ module stdlib_io
   !! ([Specification](../page/specs/stdlib_io.html#getfile-read-a-whole-ascii-file-into-a-string-variable))
   !! 
   !!### Summary 
-  !! Function interface for reading the content of a file into a string.
+  !! Subroutine interface for reading the content of a file into a string.
   !!
   !!### Description
   !! 
-  !! This function reads the entirety of a specified ASCII file and returns it as a string. The optional 
+  !! This subroutine reads the entirety of a specified ASCII file and returns it as a string. The optional 
   !! `err` argument allows for handling errors through the library's `state_type` class. 
   !! An optional `logical` flag can be passed to delete the file after reading.  
   !! 
@@ -551,9 +551,11 @@ contains
   !> 
   !> Reads a whole ASCII file and loads its contents into a string variable.
   !> The function handles error states and optionally deletes the file after reading.
-  type(string_type) function getfile(fileName,err,delete) result(file)
+  subroutine getfile(fileName,file,err,delete) 
       !> Input file name
       character(*), intent(in) :: fileName
+      !> Output string variable
+      type(string_type), intent(out) :: file
       !> [optional] State return flag. On error, if not requested, the code will stop.
       type(state_type), optional, intent(out) :: err
       !> [optional] Delete file after reading? Default: do not delete
@@ -637,6 +639,6 @@ contains
       call move(from=fileString,to=file)
       call err0%handle(err)
 
-  end function getfile
+  end subroutine getfile
 
 end module stdlib_io

test/io/test_getline.f90

@@ -150,7 +150,7 @@ subroutine test_getfile_missing(error)
         type(string_type) :: fileContents
         type(state_type) :: err
 
-        fileContents = getfile("nonexistent_file.txt", err)
+        call getfile("nonexistent_file.txt", fileContents, err)
 
         ! Check that an error was returned
         call check(error, err%error(), "Error not returned on a missing file")
@@ -175,7 +175,7 @@ subroutine test_getfile_empty(error)
         close(ios)
 
         ! Read and delete it
-        fileContents = getfile(filename, err, delete=.true.)
+        call getfile(filename, fileContents, err, delete=.true.)
 
         call check(error, err%ok(), "Should not return error reading an empty file")
         if (allocated(error)) return
@@ -203,7 +203,7 @@ subroutine test_getfile_non_empty(error)
         close(ios)
 
         ! Read and delete it
-        fileContents = getfile(filename, err, delete=.true.)
+        call getfile(filename, fileContents, err, delete=.true.)
 
         call check(error, err%ok(), "Should not return error reading a non-empty file")
         if (allocated(error)) return