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.

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

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

Description: Joins a String vector tokens into self with given separator. Default separator is 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])
  • 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 LF)
  • column_separator is optional and of type character(len=*) (default is ",")
  • 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 whose default values are LF and "," respectively.

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

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.

trim

For self a scalar or array variable of any rank and of type String:

    result = self%trim()

Description: Returns a copy of a String elementally in which each string slice component has been trimmed of any leading or trailing whitespace.

trim_inplace

For self a scalar or array variable of any rank and of type String:

    call self%trim_inplace()

Description: Removes any leading or trailing whitespace of 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])
  • 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 LF)
  • column_separator is optional and of type character(len=*) (default is ",")
  • 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 default values are LF and "," respectively, 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

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