String methods

  • Austin C Bullock

type String

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.

Type-bound procedures

as_str

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).

cast

Description: A generic binding for the interface cast.

count

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 String

Description: 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.

echo

Description: A generic binding for the interface echo.

empty

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().

ends_with

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 String

Description: 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.

find

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 String
  • occurrence 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.

join

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.

len

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().

push

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 String

Description: 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.

read_file

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 integer
  • errmsg 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.

read_line

For self a scalar variable of type String:

    call self%read_line(unit [, stat, errmsg])
  • unit is of type integer, connected for formatted sequential input
  • stat is optional and of type integer
  • errmsg 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

replace

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 String
  • substring is of type character(len=*) or String
  • back 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.

replace_inplace

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 String
  • substring is of type character(len=*) or String
  • back 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.

split

Description: A generic binding for the interface split.

starts_with

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 String

Description: 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.

to_lower

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.

to_upper

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.

trim

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".

trim_inplace

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.

write_file

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 integer
  • errmsg 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.

write(formatted)

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)".