flibs/strings(n) 1.1 "flibs"

Name

flibs/strings - Manipulate and store strings

Table Of Contents

Synopsis

Description

The file textstr.f90 contains three fairly small modules, designed for simple text manipulation and storage:

The facilities offered by these modules are geared to storage and some basic manipulations. They are not meant to be a complete module for arbitrary-length strings. hence the module.

DATA TYPES

The modules singleline_text and multiline_text each a suitable derived type:

type(TEXT_STRING)

Type to hold a string of arbitrary length.

type(MULITLINE_TEXT)

Type to hold a set of strings of arbitrary length.

ROUTINES

The module edit_text contains the following routines:

use edit_text

To import the subroutines, use this module.

call edit_delete( string, pos, length )

Delete a substring from a string.

character(len=*), intent(inout) string

String to be modified

integer, intent(in) pos

Position of the first character to be deleted

integer, intent(in) length

Length of the substring to be deleted

call edit_insert( string, pos, substring )

Insert a substring into a string.

character(len=*), intent(inout) string

String to be modified

integer, intent(in) pos

Position after which to insert the substring (use 0 to insert it before the string)

character(len=*), intent(in) substring

Subtring to be inserted

The module singleline_text contains the following routines:

use singleline_text

To import the subroutines, use this module.

length = txt_length( text )

Return the length of the text. As this is a pure function, you cna use it to define temporary strings of the correct length.

type(TEXT_STRING), intent(in) text

Text string to be examined

call txt_cleanup( text )

Clean up the storage for a previous text string. The result is an empty string.

type(TEXT_STRING), intent(inout) text

Text string to be examined

pos = txt_index( text, substring, back )

Return the index (position) of a substring in the text.

type(TEXT_STRING), intent(in) text

Text string to be examined

character(len=*), intent(in) substring

Substring to be found

logical, optional, intent(in) back

Search from the start (.false.) or from the back (.true.)

call txt_from_string( text, string )

Store a string in a text_string type. Trailing blanks in the original string are explicitly stored.

type(TEXT_STRING), intent(inout) text

Text string to be created/filled

character(len=*), intent(in) string

Ordinary string to be copied into the text string

call txt_from_string( text, string )

Store the contents of a text_string type in an ordinary string. If the string is too short, the result will be a truncated string.

type(TEXT_STRING), intent(in) text

Text string to be copied

character(len=*), intent(out) string

Ordinary string to be filled

call txt_read_from_file( lun, text, eof )

Read a text string from a file (one complete line).

integer, intent(in) lun

The LU-number of the file

type(TEXT_STRING), intent(out) text

Text string to be created/filled

logical, intent(out) eof

Indicates whether end-of-file was reached or not

call txt_write_to_file( lun, text )

Write a text string to a file (as one complete line).

integer, intent(in) lun

The LU-number of the file

type(TEXT_STRING), intent(in) text

Text string to be written

call txt_delete( text, pos, length )

Delete a substring from a text string.

type(TEXT_STRING), intent(inout) text

Text string to be modified

integer, intent(in) pos

Position of the first character to be deleted

integer, intent(in) length

Length of the substring to be deleted

call txt_insert( text, pos, substring )

Insert a substring into a string.

type(TEXT_STRING), intent(inout) text

String to be modified

integer, intent(in) pos

Position after which to insert the substring (use 0 to insert it before the string)

character(len=*), intent(in) substring

Subtring to be inserted

The module multiline_text contains the following routines:

use multiline_text

To import the subroutines, use this module.

length = mltxt_length( text )

Return the maximum length of all text strings stored. Useful to define temporary strings.

type(MULTILINE_TEXT), intent(in) text

Multiline text to be examined

length = mltxt_number( text )

Return the number of text strings stored.

type(MULTILINE_TEXT), intent(in) text

Multiline text to be examined

call mltxt_cleanup( text )

Cleans up a multiline text - all text strings are deleted temporary strings.

type(MULTILINE_TEXT), intent(in) text

Multiline text to be cleaned up

call mltxt_insert( text, pos, line )

Inserts a text string or an ordinary string as a new line of text after the given position.

type(MULTILINE_TEXT), intent(inout) text

Multiline text to be modified

integer, intent(in) pos

Position after which to insert the new line (use 0 to make it the first line)

(...), intent(in) line

Ordinary string, text_string or multine_text variable holding the text that will be inserted.

call mltxt_delete( text, first, last )

Delete the line at the given positions.

type(MULTILINE_TEXT), intent(inout) text

Multiline text to be modified

integer, intent(in) first

Position of the first line to be removed.

integer, intent(in) last

Position of the last line to be removed (optional, defaults to the first line).

call mltxt_get( text, pos, line )

Return a pointer (!) to the line at the given position. Note: no copy is made, but a pointer is returned. This means you can change the line of text via this pointer.

type(MULTILINE_TEXT), intent(inout) text

Multiline text to be examined

integer, intent(in) pos

Position of the line to be returned

type(TEXT_STRING), pointer line

Variable that will point to the line of text

call mltxt_read_file( filename, text, error )

Read an entire file into a multiline text variable.

characer(len=*), intent(in) lun

The name of the file to be read

type(TEXT_STRING), intent(out) text

Text string to be created/filled

logical, intent(out) error

Indicates whether an error occurred or not

call mltxt_write_file( text, filename, error )

Write a multiline text variable to a file.

type(TEXT_STRING), intent(out) text

Text string to be created/filled

characer(len=*), intent(in) lun

The name of the file to be written

logical, intent(out) error

Indicates whether an error occurred or not

The file textstr_func.f90 contains a single module, multiple_line_text_functions, designed for filtering multiline text:

use multiline_text_functions

To import the subroutines, use this module.

call mltxt_iterate( text, filter, first, last )

Manipulate the contents of a multiline text variable via a user-defined subroutine or object (filter). Each line within the range is visited once. Lines that get inserted along the way are not examined.

type(MULTILINE_TEXT), intent(in) text

Multiline text to be examined and possibly changed

subroutine/object filter filter

Subroutine or object that defines the filter - see below

integer, intent(in) first first

The first line to be examined (defaults to 1)

integer, intent(in) first last

The last line to be examined (defaults to the last line in the variable text)

The subroutine filter has the following interface:

    subroutine filter( pos, string, action, text_str, mltxt_str )
        integer, intent(in)          :: pos
        character(len=*), intent(in) :: string
        integer                      :: action
        type(text_string)            :: text_str
        type(multiline_text)         :: mltxt_str
    end subroutine filter

where:

  • pos is the current line number

  • string is the entire text of that line

  • action is the action to take:

    • mltxt_insert_after_text: insert the contents of the text_str variable after the current line.

    • mltxt_insert_after_mltxt: insert the contents of the mltxt_str variable after the current line.

    • mltxt_insert_before_text: insert the contents of the text_str variable before the current line.

    • mltxt_insert_before_mltxt: insert the contents of the mltxt_str variable before the current line.

    • mltxt_delete_current: delete the current line

    • mltxt_replace_text: replace the contents of the current line by that of text_str

    • mltxt_replace_mltxt: replace the contents of the current line by that of mltxt_str

    • mltxt_exit: break off the loop

    • mltxt_continue: continue with the next line (nothing is changed or added)