---

Manual Reference Pages  - slurp (3m_unicode)

---

NAME

slurp(3f) - [M_unicode:READ] read formatted UTF-8 file into a TYPE(UNICODE_TYPE) string array (LICENSE:MIT)

CONTENTS

Synopsis
Description
Options
Returns
Examples
Author
License

SYNOPSIS

function slurp(filename,iomsg) result(text)

   character(len=*),intent(in),optional              :: filename
   ! or
   type(unicode_type),intent(in),optional            :: filename

   character(len=*),intent(out),optional,allocatable :: iomsg

   type(unicode_type),allocatable,intent(out)        :: text(:)

DESCRIPTION

Uses READLINE(3) to read an entire formatted UTF-8 encoded file into a TYPE(UNICODE_TYPE) string array, each line of the file becoming an element of the output array.

    NOTE

Never casually read an entire file into memory if you can process it per line or in smaller units; as large files can consume unreasonable amounts of memory.

OPTIONS

filename
	filename to read into memory. If the filename is absent stdin will be read.
iomsg	if an error occurs iomsg will contain an error message, else it will be a null string.

RETURNS

text	array of characters that holds contents of the file

EXAMPLES

Sample program, which
	creates test input file "inputfile" and then reads it back in.

   program demo_slurp
   use M_unicode, only : slurp, ut=>unicode_type
   use M_unicode, only : add_backslash, escape
   use M_unicode, only : assignment(=)
   implicit none
   type(ut),allocatable         :: text(:)
   integer                      :: i
   character(len=:),allocatable :: iomsg
   character(len=*),parameter   :: FILENAME=’._inputfile’

   call create_test_file()

   text=slurp(FILENAME,iomsg=iomsg)

   if(iomsg.ne.’’)then
      write(*,*)’*demo_slurp* failed to load file ’//FILENAME
      write(*,*) iomsg
   else
      ! write out slurped data
      call write_text()

      ! encode with escape sequences and write data again
      do i=1,size(text)
         text(i)=add_backslash(text(i))
      enddo
      call write_text()

      ! deencode escape sequences and write data again
      do i=1,size(text)
         text(i)=escape(text(i))
      enddo
      call write_text()

        ! teardown
      deallocate(text)  ! release memory
      open(file=FILENAME,unit=10)
      close(unit=10,status=’delete’)
   endif
   contains
   subroutine write_text()
      write(*,’(a)’)repeat(’=’,80)
      write(*,’(*(a:))’)(text(i)%character(),new_line(’a’),i=1,size(text))
   end subroutine write_text

   subroutine create_test_file()
   ! create test file
   open(file=FILENAME,unit=10,action=’write’)
   ! (Used by Microsoft Office as sample text for Croatian language.)
   write( *,’(a)’)’Croation pangram:’
   write( *,’(a)’)’’
   write(10,’(a)’)’Gojazni đačić s biciklom drži hmelj i finu’
   write(10,’(a)’)’vatu u džepu nošnje.’
   write(10,’(a)’)’’
   write( *,’(a)’)’The overweight little schoolboy with a bike is holding’
   write( *,’(a)’)’hops and fine cotton in the pocket of his attire.’
   close(unit=10)
   end subroutine create_test_file

   end program demo_slurp

Results:

 > Croation pangram:
 >
 > The overweight little schoolboy with a bike is holding
 > hops and fine cotton in the pocket of his attire.
 >
 > Gojazni đačić s biciklom drži hmelj i finu
 > vatu u džepu nošnje.
 >
 > Gojazni \u0111a\u010Di\u0107 s biciklom dr\u017Ei hmelj i finu
 > vatu u d\u017Eepu no\u0161nje.
 >
 > Gojazni đačić s biciklom drži hmelj i finu
 > vatu u džepu nošnje.
 >

AUTHOR

John S. Urban

LICENSE

    MIT

---