String Derived Type

type, public :: String

A growable string type for advanced character handling and text I/O.

For a user reference, see String, String methods, and Operators.

Note

TECHNICAL NOTE: The String type is memory safe. The user will never need to be concerned about accessing invalid memory when using the String type. Any operation defined in this documentation for the String type which may involve a String with an unallocated component, or arrays of Strings in which some of the elements may have unallocated components, is well-defined. In all such cases, the component is treated as the empty string.


Constructor

public interface String

Function for returning a String representation of numbers.

For a user reference, see String, String methods, and Operators.

  • private pure elemental recursive module function new_string_from_c128(x, locale, fmt, decimals, im) result(new)

    Arguments

    Type IntentOptional Attributes Name
    complex(kind=r128), intent(in) :: x
    character(len=*), intent(in), optional :: locale
    character(len=*), intent(in), optional :: fmt
    integer, intent(in), optional :: decimals
    character(len=*), intent(in), optional :: im

    Return Value type(String)

  • private pure elemental recursive module function new_string_from_c64(x, locale, fmt, decimals, im) result(new)

    Arguments

    Type IntentOptional Attributes Name
    complex(kind=r64), intent(in) :: x
    character(len=*), intent(in), optional :: locale
    character(len=*), intent(in), optional :: fmt
    integer, intent(in), optional :: decimals
    character(len=*), intent(in), optional :: im

    Return Value type(String)

  • private pure elemental recursive module function new_string_from_c32(x, locale, fmt, decimals, im) result(new)

    Arguments

    Type IntentOptional Attributes Name
    complex(kind=r32), intent(in) :: x
    character(len=*), intent(in), optional :: locale
    character(len=*), intent(in), optional :: fmt
    integer, intent(in), optional :: decimals
    character(len=*), intent(in), optional :: im

    Return Value type(String)

  • private pure elemental recursive module function new_string_from_r128(x, locale, fmt, decimals) result(new)

    Arguments

    Type IntentOptional Attributes Name
    real(kind=r128), intent(in) :: x
    character(len=*), intent(in), optional :: locale
    character(len=*), intent(in), optional :: fmt
    integer, intent(in), optional :: decimals

    Return Value type(String)

  • private pure elemental recursive module function new_string_from_r64(x, locale, fmt, decimals) result(new)

    Arguments

    Type IntentOptional Attributes Name
    real(kind=r64), intent(in) :: x
    character(len=*), intent(in), optional :: locale
    character(len=*), intent(in), optional :: fmt
    integer, intent(in), optional :: decimals

    Return Value type(String)

  • private pure elemental recursive module function new_string_from_r32(x, locale, fmt, decimals) result(new)

    Arguments

    Type IntentOptional Attributes Name
    real(kind=r32), intent(in) :: x
    character(len=*), intent(in), optional :: locale
    character(len=*), intent(in), optional :: fmt
    integer, intent(in), optional :: decimals

    Return Value type(String)

  • private pure elemental recursive module function new_string_from_i64(x, fmt) result(new)

    Arguments

    Type IntentOptional Attributes Name
    integer(kind=i64), intent(in) :: x
    character(len=*), intent(in), optional :: fmt

    Return Value type(String)

  • private pure elemental recursive module function new_string_from_i32(x, fmt) result(new)

    Arguments

    Type IntentOptional Attributes Name
    integer(kind=i32), intent(in) :: x
    character(len=*), intent(in), optional :: fmt

    Return Value type(String)

  • private pure elemental recursive module function new_string_from_i16(x, fmt) result(new)

    Arguments

    Type IntentOptional Attributes Name
    integer(kind=i16), intent(in) :: x
    character(len=*), intent(in), optional :: fmt

    Return Value type(String)

  • private pure elemental recursive module function new_string_from_i8(x, fmt) result(new)

    Arguments

    Type IntentOptional Attributes Name
    integer(kind=i8), intent(in) :: x
    character(len=*), intent(in), optional :: fmt

    Return Value type(String)

  • private pure elemental recursive module function new_string_from_string(x) result(new)

    Arguments

    Type IntentOptional Attributes Name
    class(String), intent(in) :: x

    Return Value type(String)

  • private pure elemental recursive module function new_string_from_char(x) result(new)

    Arguments

    Type IntentOptional Attributes Name
    character(len=*), intent(in) :: x

    Return Value type(String)

  • private pure elemental recursive module function new_string_from_empty() result(new)

    Arguments

    None

    Return Value type(String)


Finalization Procedures

final :: scrub

  • private interface scrub()

    Methods for the String type.

    Arguments

    None

Type-Bound Procedures

generic, public :: cast => cast_string_to_c128, cast_string_to_c64, cast_string_to_c32, cast_string_to_r128, cast_string_to_r64, cast_string_to_r32, cast_string_to_i64, cast_string_to_i32, cast_string_to_i16, cast_string_to_i8

  • private pure elemental recursive module subroutine cast_string_to_c128(substring, into, locale, fmt, im)

    Arguments

    Type IntentOptional Attributes Name
    class(String), intent(in) :: substring
    complex(kind=r128), intent(out) :: into
    character(len=*), intent(in), optional :: locale
    character(len=*), intent(in), optional :: fmt
    character(len=*), intent(in), optional :: im

  • private pure elemental recursive module subroutine cast_string_to_c64(substring, into, locale, fmt, im)

    Arguments

    Type IntentOptional Attributes Name
    class(String), intent(in) :: substring
    complex(kind=r64), intent(out) :: into
    character(len=*), intent(in), optional :: locale
    character(len=*), intent(in), optional :: fmt
    character(len=*), intent(in), optional :: im

  • private pure elemental recursive module subroutine cast_string_to_c32(substring, into, locale, fmt, im)

    Arguments

    Type IntentOptional Attributes Name
    class(String), intent(in) :: substring
    complex(kind=r32), intent(out) :: into
    character(len=*), intent(in), optional :: locale
    character(len=*), intent(in), optional :: fmt
    character(len=*), intent(in), optional :: im

  • private pure elemental recursive module subroutine cast_string_to_r128(substring, into, locale, fmt)

    Arguments

    Type IntentOptional Attributes Name
    class(String), intent(in) :: substring
    real(kind=r128), intent(out) :: into
    character(len=*), intent(in), optional :: locale
    character(len=*), intent(in), optional :: fmt

  • private pure elemental recursive module subroutine cast_string_to_r64(substring, into, locale, fmt)

    Arguments

    Type IntentOptional Attributes Name
    class(String), intent(in) :: substring
    real(kind=r64), intent(out) :: into
    character(len=*), intent(in), optional :: locale
    character(len=*), intent(in), optional :: fmt

  • private pure elemental recursive module subroutine cast_string_to_r32(substring, into, locale, fmt)

    Arguments

    Type IntentOptional Attributes Name
    class(String), intent(in) :: substring
    real(kind=r32), intent(out) :: into
    character(len=*), intent(in), optional :: locale
    character(len=*), intent(in), optional :: fmt

  • private pure elemental recursive module subroutine cast_string_to_i64(substring, into, fmt)

    Arguments

    Type IntentOptional Attributes Name
    class(String), intent(in) :: substring
    integer(kind=i64), intent(out) :: into
    character(len=*), intent(in), optional :: fmt

  • private pure elemental recursive module subroutine cast_string_to_i32(substring, into, fmt)

    Arguments

    Type IntentOptional Attributes Name
    class(String), intent(in) :: substring
    integer(kind=i32), intent(out) :: into
    character(len=*), intent(in), optional :: fmt

  • private pure elemental recursive module subroutine cast_string_to_i16(substring, into, fmt)

    Arguments

    Type IntentOptional Attributes Name
    class(String), intent(in) :: substring
    integer(kind=i16), intent(out) :: into
    character(len=*), intent(in), optional :: fmt

  • private pure elemental recursive module subroutine cast_string_to_i8(substring, into, fmt)

    Arguments

    Type IntentOptional Attributes Name
    class(String), intent(in) :: substring
    integer(kind=i8), intent(out) :: into
    character(len=*), intent(in), optional :: fmt

generic, public :: count => count_substring_chars, count_substring_string

  • private interface count_substring_chars()

    Methods for the String type.

    Arguments

    None

  • private interface count_substring_string()

    Methods for the String type.

    Arguments

    None

generic, public :: echo => echo_string

  • private impure recursive module subroutine echo_string(substring, file, append, terminator, stat, errmsg)

    Arguments

    Type IntentOptional Attributes Name
    class(String), intent(in) :: substring
    character(len=*), intent(in) :: file
    logical, intent(in), optional, target :: append
    character(len=*), intent(in), optional, target :: terminator
    integer, intent(out), optional, target :: stat
    character(len=*), intent(out), optional, target :: errmsg

generic, public :: push => push_chars, push_string

  • private interface push_chars()

    Methods for the String type.

    Arguments

    None

  • private interface push_string()

    Methods for the String type.

    Arguments

    None

generic, public :: replace => replace_ch_copy, replace_st_copy, replace_chst_copy, replace_stch_copy

  • private interface replace_ch_copy()

    Methods for the String type.

    Arguments

    None

  • private interface replace_st_copy()

    Methods for the String type.

    Arguments

    None

  • private interface replace_chst_copy()

    Methods for the String type.

    Arguments

    None

  • private interface replace_stch_copy()

    Methods for the String type.

    Arguments

    None

generic, public :: replace_inplace => replace_ch_inplace, replace_st_inplace, replace_chst_inplace, replace_stch_inplace

  • private interface replace_ch_inplace()

    Methods for the String type.

    Arguments

    None

  • private interface replace_st_inplace()

    Methods for the String type.

    Arguments

    None

  • private interface replace_chst_inplace()

    Methods for the String type.

    Arguments

    None

  • private interface replace_stch_inplace()

    Methods for the String type.

    Arguments

    None

generic, public :: split => split_string

  • private pure recursive module function split_string(substring, separator) result(tokens)

    Arguments

    Type IntentOptional Attributes Name
    class(String), intent(in) :: substring
    character(len=*), intent(in), optional :: separator

    Return Value type(String), allocatable, (:)

generic, public :: write(formatted) => write_string

  • private interface write_string()

    Methods for the String type.

    Arguments

    None

procedure, public, pass(self) :: as_str

  • interface

    Methods for the String type.

    private pure recursive module function as_str(self) result(string_slice)

    Returns a copy of the string slice component of a scalar String.

    For a user reference, see as_str.

    Arguments

    Type IntentOptional Attributes Name
    class(String), intent(in) :: self

    Return Value character(len=:), allocatable

procedure, public, pass(self) :: empty

  • interface

    Methods for the String type.

    private pure elemental recursive module subroutine empty(self)

    Sets the string slice component to the empty string elementally. This procedure is identical in function to the assignment self = String().

    For a user reference, see empty.

    Arguments

    Type IntentOptional Attributes Name
    class(String), intent(inout) :: self

procedure, public, pass(self) :: join => join_into_self

  • interface

    Methods for the String type.

    private pure recursive module subroutine join_into_self(self, tokens, separator)

    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 user reference, see join.

    Arguments

    Type IntentOptional Attributes Name
    class(String), intent(inout) :: self
    type(String), intent(in) :: tokens(:)
    character(len=*), intent(in), optional :: separator

procedure, public, pass(self) :: len => length

  • interface

    Methods for the String type.

    private pure elemental recursive module function length(self) result(self_len)

    Returns the length of the string slice component elementally. Unallocated components return -1.

    For a user reference, see len.

    Arguments

    Type IntentOptional Attributes Name
    class(String), intent(in) :: self

    Return Value integer

procedure, public, pass(self) :: len64 => length64

  • interface

    Methods for the String type.

    private pure elemental recursive module function length64(self) result(self_len)

    Returns the length of the string slice component elementally. Unallocated components return -1. This function is identical to len for strings of 2,147,483,647 bytes or smaller.

    For a user reference, see len.

    Arguments

    Type IntentOptional Attributes Name
    class(String), intent(in) :: self

    Return Value integer(kind=i64)

procedure, public, pass(self) :: read_file

  • interface

    Methods for the String type.

    private impure recursive module subroutine read_file(self, file, cell_array, row_separator, column_separator, stat, errmsg)

    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 COMMA respectively.

    For a user reference, see read_file.

    Arguments

    Type IntentOptional Attributes Name
    class(String), intent(inout) :: self
    character(len=*), intent(in) :: file
    type(String), intent(out), optional, allocatable :: cell_array(:,:)
    character(len=*), intent(in), optional, target :: row_separator
    character(len=*), intent(in), optional, target :: column_separator
    integer, intent(out), optional, target :: stat
    character(len=*), intent(out), optional, target :: errmsg

procedure, public, pass(self) :: trim => trim_copy

  • interface

    Methods for the String type.

    private pure elemental recursive module function trim_copy(self) result(new)

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

    For a user reference, see trim.

    Arguments

    Type IntentOptional Attributes Name
    class(String), intent(in) :: self

    Return Value type(String)

procedure, public, pass(self) :: trim_inplace

  • interface

    Methods for the String type.

    private pure elemental recursive module subroutine trim_inplace(self)

    Removes any leading or trailing whitespace of the string slice component of a String elementally and in place.

    For a user reference, see trim_inplace.

    Arguments

    Type IntentOptional Attributes Name
    class(String), intent(inout) :: self

procedure, public, pass(self) :: write_file

  • interface

    Methods for the String type.

    private impure recursive module subroutine write_file(self, cell_array, file, row_separator, column_separator, append, stat, errmsg)

    Writes the content of a cell array to a text file. The cell array's entire contents are populated into self and then streamed to an external text file using the designated row_separator and column_separator whose default values are LF and COMMA respectively.

    For a user reference, see write_file.

    Arguments

    Type IntentOptional Attributes Name
    class(String), intent(inout) :: self
    type(String), intent(in) :: cell_array(:,:)
    character(len=*), intent(in) :: file
    character(len=*), intent(in), optional, target :: row_separator
    character(len=*), intent(in), optional, target :: column_separator
    logical, intent(in), optional, target :: append
    integer, intent(out), optional, target :: stat
    character(len=*), intent(out), optional, target :: errmsg