| title |
|---|
stringlist |
[TOC]
Fortran has supported variable-length strings since the 2003 standard, but it does not have a native type to handle collections of strings of different lengths. Such collections are quite useful though and the language allows us to define a derived type that can handle such collections.
The stdlib_stringlist module defines a derived type that is capable of
storing a list of strings and of manipulating them.
Methods include:
- inserting strings at a given position
- replacing strings at a given position
- deleting a single string or a range of strings
- retrieving a string or a range of strings at a given position
- finding the position of a particular string or a string which contains some substring
- sorting the list
The module implements what are effectively infinitely long lists: a position is represented as a positive integer, but there is no "out-of-bound" index. That is, the following piece of code will simply work:
type(stringlist_type) :: list
! Add two strings ...
call list%insert( list_head, "The first string" )
call list%insert( 20, "The last string" )
write(*,*) 'The last: ', list%get(list_end)
write(*,*) 'Beyond that: ', list%get(30)The special position list_head represents the first element, though a value
of 1 is equivalent. Likewise, the special position list_end represents the position
of the last element and the position list_after_end the position directly after
the last element. You can use these positions to insert a string before the current
first string that is already in the list or to insert after the last string that
has been inserted.
If you specify a position beyond the last, the list%get() method simply returns an empty
string. The same holds for zero or negative indices.
For inserting one or more elements, a zero or negative index is interpreted to mean the first, an index beyond the last as the one after the last - this means effectively that the element is appended.
If you do:
call list%insert( 1, 'The first string' )
call list%insert( -10, 'A new first string' )the second inserted string will become the string at the first position (1) and all other strings are shifted by one:
element 1: 'A new first string'
element 2: 'The first string'
element 3: ...
If you need the last but one string, you can do so in this way:
write(*,*) 'The last but one: ', list%get(list_end-1)So, it is possible to do simple arithmetic.
Experimental
The type holds a small number of components and gives access to a number of procedures, some of which are implemented as subroutines, others as functions or as operations.
The following methods are defined:
| Method | Class | Description |
|---|---|---|
delete |
Subroutine | Delete one or more strings from the list |
destroy |
Subroutine | Destroy the contents of the list |
get |
Function | Get a string from a particular position |
index |
Function | Find the index of a string in a list |
index_sub |
Function | Find the index of a string containing a partilcar substring |
insert |
Subroutine | Insert a string or a list after a given position |
length |
Function | Return the index of the last set position |
range |
Function | Retrieve a range of strings from the list |
replace |
Subroutine | Replace one or more stringa between two positions |
sort |
Function | Sort the list and return the result as a new list |
= |
Assignment | Copy a list |
// |
Operation | Concatenate a list with a string or concatenate two lists |
Experimental
Delete one or more strings from the list via a given position or positions.
call list % [[stringlist_type(type):delete(bound)]]( first [, last] )
Subroutine
list: the stringlist variable from which to delete one or more strings
first: the index of the first string to be deleted
last (optional): the index of the last string to be deleted. If left out, only one string is deleted.
If the value is lower than that of first, the range is considered to be empty and nothing is deleted.
Experimental
Destroy the entire contents of the list. As the variable holding the list is simply a derived type, the variable itself is not destroyed.
call list % [[stringlist_type(type):destroy(bound)]]
Subroutine
list: the stringlist variable from which to delete all strings
Experimental
Get the string at the given position.
string = list % [[stringlist_type(type):get(bound) ( idx )]]
Function
list: the stringlist variable to retrieve a string from
idx: the index of the string to be retrieved (see the section on positions
A copy of the string stored at the indicated position.
Experimental
Get the position of the first stored string that matches the given string, if back is not present or false. If back is
false, return the position of the last stored string that matches. Note that trailing blanks are ignored.
idx = list % [[stringlist_type(type):index(bound) ( string, back )]]
Function
list: the stringlist variable to retrieve a string from
string: the string to be found in the list
back (optional): logical argument indicating the first occurrence should be returned (false) or the last (true)
The result is either the index of the string in the list or -1 if the string was not found
Because trailing blanks are ignored, the following calls will give the same result:
write(*,*) list%index( 'A' )
write(*,*) list%index( 'A ' )Experimental
Get the position of the first stored string that contains the given substring, if back is not present or false. If back is
false, return the position of the last stored string that contains it.
idx = list % [[stringlist_type(type):index_sub(bound) ( substring, back )]]
Function
list: the stringlist variable to retrieve a string from
substring: the substring in question
back (optional): logical argument indicating the first occurrence should be returned (false) or the last (true)
The result is either the index of the string in the list or -1 if the string was not found
Experimental
Insert one or more strings at a given position. The position may be anything as explained in the section on positions. A single string may be inserted, another list of strings or a plain array of strings. In all cases trailing blanks, if any, are retained.
idx = list % [[stringlist_type(type):insert(bound) ( idx, string )]]
Subroutine
list: the stringlist variable to insert the string(s) into
idx: the position after which the strings should be inserted
string: the string to be inserted, a list of strings or a plain array of strings
Experimental
Return the length of the list, defined as the highest index for which a string has been assigned. You can place strings in any position without needing to fill in the intervening positions.
length = list % [[stringlist_type(type):length(bound) ()]]
Function
list: the stringlist variable to retrieve the length from
Returns the highest index of a string that has been set.
Experimental
Retrieve the strings occurring between the given positions as a new list.
rangelist = list % [[stringlist_type(type):range(bound) ( first, last )]]
Function
list: the stringlist variable to insert the string(s) into
first: the position of the first string to be retrieved
last: the position of the last string to be retrieved
The result is a new list containing all the strings that appear from the first to the last position, inclusively.
Experimental
Replace one or more strings between two given positions. The new strings may be given as a single string, a list of strings or a plain array.
call list % [[stringlist_type(type):replace(bound) ( first, last, string )]]
Subroutine
list: the stringlist variable to replace the string(s) in
first: the position of the first string to be retrieved
last: the position of the last string to be retrieved. If only one string needs to be replaced by another string,
then this argument can be left out.
string: the string to be inserted, a list of strings or a plain array of strings
Experimental
Create a new list consisting of the sorted strings of the given list. The strings are sorted according to ASCII, either in ascending order or descending order.
sortedlist = list % [[stringlist_type(type):sort(bound) ( ascending )]]
Subroutine
list: the stringlist variable of which the contents should be copied
ascending (optional): if not present or true, sort the list in ascending order, otherwise descending
The contents of the given list is sorted and then stored in the new list.
Experimental
Copy an existing list to a new one. The original list remains unchanged.
copylist = list
Assignment
list: the stringlist variable to be copied
Experimental
Concatenate a list with a string, a list of strings or a plain array
concatenatedlist = list // string
concatenatedlist = string // list
Assignment
list: the stringlist variable to be concatenated
string: the string to be concatenated, a list of strings or a plain array of strings
A stringlist that contains the concatenation of the two operands.
Additional methods:
filter
map
Suggestions from the discussion