Description: A growable string type for advanced character handling and text I/O.
Note
In addition to the functionality provided through type-bound
procedures, the String type may be useful in array contexts for which
the user requires arrays of strings which may have non-identical
lengths, whose lengths may not be known, whose lengths may need to vary
during run time, or in any other context in which the intrinsic
character type is insufficient.
For self a scalar variable of type String:
result = self%as_str()
Description: Returns a copy of the string slice component of a scalar
String. This procedure is identical in function to the type
conversion result = str(self).
Description: A generic binding for the interface cast.
For self a scalar or array variable of any rank and of type String:
result = self%count(match)
match is of type character(len=*) or StringDescription: Returns number of non-overlapping occurrences of a substring elementally.
Note
match may be a scalar or the same rank and shape as self.
The result is a default integer. If a string may hold more than
2,147,483,647 occurrences, use self%count64(match), which returns an
integer of kind int64.
Description: A generic binding for the interface echo.
For self a scalar or array variable of any rank and of type String:
call self%empty()
Description: Sets the string slice component to the empty string
elementally. This procedure is identical in function to the assignment
self = String().
For self a scalar or array variable of any rank and of type String:
result = self%ends_with(substring)
substring is of type character(len=*) or StringDescription: Returns .true. where self ends with substring,
elementally. Every string ends with the empty string, and trailing
blanks count. The same test for character values is
ends_with in io_strings.
For self a scalar or array variable of any rank and of type String:
result = self%find(pattern [, occurrence, consider_overlapping])
pattern is of type character(len=*) or Stringoccurrence is optional and of type integer (default is 1)consider_overlapping is optional and of type logical (default
is .true.)Description: Returns the position where the occurrenceth occurrence
of pattern starts in self, elementally, or 0 if there is none.
Occurrences may overlap unless consider_overlapping is .false., so
String("aaaa")%find("aa", occurrence=2) is 2, and 3 without
overlap. An empty pattern gives 0. This follows find in the
Fortran standard library; the same function for character values is
find in io_strings.
For self a scalar variable of type String:
call self%join(tokens [, separator])
tokens is of type type(String), dimension(:)separator is optional and of type character(len=*) (default is
IOFL_SPACE)Description: Joins a String vector tokens into self with given
separator. Default separator is IOFL_SPACE. The string slice component
will be replaced if already allocated.
For a functional version of join, see join.
For self a scalar or array variable of any rank and of type String:
result = self%len()
Description: Returns the length of the string slice component
elementally. Unallocated components return -1. For strings larger
than 2,147,483,647 bytes, use self%len64().
For self a scalar or array variable of any rank and of type String:
call self%push(substring)
substring is of type character(len=*) or StringDescription: Appends to the string slice component elementally in
place. This procedure is identical in function to the
concatenation operators with self
assignment: self = self // substring and self = self + substring.
Note
substring may be a scalar or the same rank and shape as self.
For self a scalar variable of type String:
call self%read_file(file [, cell_array, row_separator, column_separator, stat, errmsg, format])
file is of type character(len=*)cell_array is optional and of type type(String), allocatable, dimension(:,:)row_separator is optional and of type character(len=*)
(default is IOFL_LF)column_separator is optional and of type character(len=*)
(default is a tab for a .tsv file, and "," otherwise)stat is optional and of type integererrmsg is optional and of type character(len=*)Description: Reads raw text file contents into self and optionally
populates a cell array using the designated row_separator and
column_separator. Their defaults are IOFL_LF, and a tab for a .tsv
file or "," otherwise.
Note
file may be a relative path, but absolute paths are not
guaranteed to work on every platform.
Note
The cell_array must be allocatable and will be re-allocated
internally (if already allocated).
Note
A cell that starts with a double quote runs to the closing quote, and any separators inside it are part of the cell. Two double quotes in a row inside it stand for one, and the outer quotes are not kept. A double quote anywhere else in a cell is an ordinary character. A quote that is not closed is an error.
Note
The first row sets the number of columns. A row with fewer cells
is filled with empty cells, and a row with more is an error. Trailing
blank lines and a missing final newline do not change the number of
rows. With the default row_separator, CRLF line endings are
accepted.
For self a scalar variable of type String:
call self%read_line(unit [, stat, errmsg])
unit is of type integer, connected for formatted sequential inputstat is optional and of type integererrmsg is optional and of type character(len=*)Description: Reads the next record from unit into self, keeping any
leading and trailing blanks. A line may be of any length, and the last
line of a file need not end in a newline.
At the end of the file, stat satisfies the intrinsic is_iostat_end.
If stat is not present, the end of the file or any other error ends the
program with error stop:
do
call line%read_line(unit, stat=stat)
if ( is_iostat_end(stat) ) exit
! ... use line ...
end do
For self a scalar or array variable of any rank and of type String:
result = self%replace(match, substring [, back])
match is of type character(len=*) or Stringsubstring is of type character(len=*) or Stringback is optional and of type logical (default is .false.)Description: Matches and replaces all occurrences of a substring
elementally. If back is .true., then self is scanned from back to
front, which may result in a different outcome in the case that match
is overlapping itself.
Note
match and substring may be any combination of character
and String, and may be any combination of scalars or arrays with the
same rank and shape as self, with the same rank/shape matching rules
applying to back.
For self a scalar or array variable of any rank and of type String:
call self%replace_inplace(match, substring [, back])
match is of type character(len=*) or Stringsubstring is of type character(len=*) or Stringback is optional and of type logical (default is .false.)Description: Matches and replaces all occurrences of a substring
elementally in place. If back is .true., then self is scanned
from back to front, which may result in a different outcome in the
case that match is overlapping itself.
Note
match and substring may be any combination of character and
String, and may be any combination of scalars or arrays with the same
rank and shape as self, with the same rank/shape matching rules
applying to back.
Description: A generic binding for the interface split.
For self a scalar or array variable of any rank and of type String:
result = self%starts_with(substring)
substring is of type character(len=*) or StringDescription: Returns .true. where self starts with substring,
elementally. Every string starts with the empty string, and trailing
blanks count. The same test for character values is
starts_with in io_strings.
For self a scalar or array variable of any rank and of type String:
result = self%to_lower()
Description: Returns a copy of self elementally with the ASCII
letters A to Z in lower case. Other characters are unchanged.
For self a scalar or array variable of any rank and of type String:
result = self%to_upper()
Description: Returns a copy of self elementally with the ASCII
letters a to z in upper case. Other characters are unchanged.
For self a scalar or array variable of any rank and of type String:
result = self%trim([chars])
chars is optional and of type character(len=*)Description: Returns a copy of a String elementally in which each
string slice component has been trimmed of any leading or trailing
characters in chars. Without chars, it trims whitespace, which
means a space, TAB, CR, LF, vertical tab or form feed.
String("--name--")%trim("-") is "name".
For self a scalar or array variable of any rank and of type String:
call self%trim_inplace([chars])
chars is optional and of type character(len=*)Description: Removes any leading or trailing characters in chars,
or whitespace if chars is absent, from the string slice component of
a String elementally and in place.
For self a scalar variable of type String:
call self%write_file(cell_array, file [, row_separator, column_separator, append, stat, errmsg, format])
cell_array is of type type(String), dimension(:,:)file is of type character(len=*)row_separator is optional and of type character(len=*)
(default is IOFL_LF)column_separator is optional and of type character(len=*)
(default is a tab for a .tsv file, and "," otherwise)append is optional and of type logical (default is .false.)stat is optional and of type integererrmsg is optional and of type character(len=*)Description: Writes the content of a cell array to a text file. The
cell array's entire contents are populated into self using the
designated row_separator and column_separator, whose defaults are
IOFL_LF, and a tab for a .tsv file or "," otherwise, and then streamed to an external text
file. The file will be created if it does not exist, and will be
appended to if append is .true..
Note
A cell containing a separator, a double quote, CR or LF is
written in double quotes, with any double quotes in it doubled, so that
read_file returns it unchanged. An unallocated cell is
written as an empty cell. Other cells are written as they are.
Note
file may be a relative path, but absolute paths are not
guaranteed to work on every platform.
For substring a scalar or array of any rank and of type String:
print "(DT)", substring
write(unit, "(DT)") substring
Description: Formatted write DTIO procedure for type String.
Note
When performing a formatted write to unit, use the derived-type
edit descriptor format fmt="(DT)".