flibs/m_vstringlist(n) 1.0 "flibs"
flibs/m_vstringlist - Processing string list
TABLE OF CONTENTS
SYNOPSIS
DESCRIPTION
OVERVIEW
Design
Preprocessing
METHODS
TODO
COPYRIGHT
| vstrlist_new (this ?args?) |
| vstrlist_new (this) |
| vstrlist_new (this string) |
| vstrlist_new (this char_string) |
| vstrlist_new (this array) |
| vstrlist_new (this list) |
| vstrlist_new (this length) |
| vstrlist_free (this) |
| vstrlist_length (this) |
| vstrlist_exists (this) |
| vstrlist_index (this , icomponent) |
| vstrlist_append (this , string) |
| vstrlist_append (this , string) |
| vstrlist_append (this , list) |
| vstrlist_concat (this , string) |
| vstrlist_concat (this , string) |
| vstrlist_concat (this , list) |
| vstrlist_insert (this , strindex , string) |
| vstrlist_insert (this , strindex , string) |
| vstrlist_range (this , first , last) |
| vstrlist_range (this , first , last) |
| vstrlist_set (this , strindex , string) |
| vstrlist_set (this , strindex , string) |
| vstrlist_split (this ?, splitChars?) |
| vstrlist_split (this ?, splitChars?) |
| vstrlist_join (this ?, joinString?) |
| vstrlist_join (this ?, joinString?) |
| vstrlist_search (this pattern ?, first? ?, notmatch? ?, exact?) |
| vstrlist_search (this pattern ?, first? ?, notmatch? ?, exact?) |
| vstrlist_lsearch (this pattern ?, first? ?, notmatch? ?, exact?) |
| vstrlist_lsearch (this pattern ?, first? ?, notmatch? ?, exact?) |
| vstrlist_sort (this ?, increasing? ?, classtype? ?, unique?) |
| vstrlist_sort (this , command ?, unique?) |
|
This module provides OO services to manage lists of
vstrings.
A list of strings can be created with vstrlist_new and
several kinds of input arguments. With no additionnal arguments,
the vstrlist_new method creates a list with no items :
| |
call vstrlist_new ( list )
|
If one gives one string, the list is created with 1 element.
One can also give an array of strings to the vstrlist_new method.
The list is destroyed with vstrlist_free.
The number of elements in the list can be computed with
vstrlist_length while vstrlist_exists allows to known
if a list has been created.
Several methods are provided to acces to the elements of one list
of strings, for example vstrlist_index, vstrlist_range and vstrlist_set.
The vstrlist_set method allows to set the element at a given index.
The strindex-th item of the list can be accessed with vstrlist_index :
| |
string1 = vstrlist_index ( list , 2 )
|
The vstrlist_range method returns a new list made of the elements
which index is between two given integers :
| |
list2 = vstrlist_range ( list , 2 , 3 )
|
To add items to a list, one can use vstrlist_append, vstrlist_concat
or vstrlist_insert.
The vstrlist_concat and vstrlist_insert methods return a new list
while vstrlist_append add one item to an existing list (therefore
increasing the number of elements in the list). In the following
example, a new list made of 3 items is created :
| |
call vstrlist_new ( list )
call vstrlist_append ( list , "fortran 77" )
call vstrlist_append ( list , "fortran 90" )
call vstrlist_append ( list , "fortran 95" )
call vstrlist_append ( list , "fortran 2003" )
call vstrlist_free ( list )
|
The vstrlist_split method allows to split a vstring into an list
of vstrings each time one character is found in a vstring.
The vstrlist_join method concatenates an list of vstrings,
using a vstring as the join between the components.
In the following example, the string is split at each dot
and the number of components is 3 :
| |
call vstring_new ( string1 , "comp.lang.fortran" )
strlist = vstrlist_split ( string1 , "." )
|
One can search for a pattern in a list. The vstrlist_search
returns the index of the found string while vstrlist_lsearch
returns the list of matching strings. These methods
are based on vstring_match and therefore are powerfull
tools to process strings.
In the following example, one searches for all fortran
compilers from the 90s (based on the previous sample list):
| |
list2 = vstrlist_search ( list , "fortran 9*" )
|
This component has been designed with OO principles in mind.
This is why the first argument of every method is named "this",
which is the current object.
If another string is required as a second argument, it may be either
of type dynamic or as a character(len=*) type, to improve
usability.
This component is meant to evolve following the fortran 2003 standard
and OO type-bound procedures.
The following preprocessing macro must be considered :
- _VSTRINGLIST_ALLOCATABLE or _VSTRINGLIST_POINTER : see the section
"Allocatable or pointer" in the documentation of the m_vstring module.
In the following definitions, the this argument has,
depending on the method, one of the the following definitions :
- type ( t_vstringlist ) , intent(inout) :: this
-
- type ( t_vstringlist ) , intent(in) :: this
-
The "intent(in)" or "intent(inout)" declaration depends on the
method and is what it is expected to be (if not, it is a bug).
- vstrlist_new (this ?args?)
-
Generic constructor. Creates the new string list "this".
- vstrlist_new (this)
-
Creates a new empty string list with 0 string.
- vstrlist_new (this string)
-
- type ( t_vstring ) , intent(in) :: string
-
Creates a new string list with one element : the string string.
- vstrlist_new (this char_string)
-
- character(LEN=*), intent(in) :: char_string
-
Creates a new string list with one element : the character(len=*) string string.
- vstrlist_new (this array)
-
- type ( t_vstring ) , dimension (:), intent(in) :: array
-
Creates a new string list with the strings of the array array.
The number of elements in the new string list is the length of the array.
- vstrlist_new (this list)
-
- type ( t_vstringlist ), intent(in) :: list
-
Creates a new string list with from the existing list of strings list.
This implements the copy of a list of strings.
- vstrlist_new (this length)
-
- integer , intent(in) :: length
-
Creates a new string list made of length empty strings.
- vstrlist_free (this)
-
Destructor.
The use of the destructor is OPTIONAL.
See the thread " New ISO_VARYING_STRING implementation
(without memory leaks)" on comp.lang.fortran :
"On most systems, memory is memory :-). However, there is a
difference between how ALLOCATABLE variables and POINTER
variables are handled. ALLOCATABLE variables are always
deallocated automatically when thay go out of scope (unless
they have the SAVE attribute). POINTER variables usually
are not. The reason is that the program may have associated
additional pointers, that aren't going out of scope, with the
same target as the one that is."
- vstrlist_length (this)
-
Returns the length, that is, the number of strings, in the current
list of strings.
- vstrlist_exists (this)
-
Returns .true. if the string list has allready been created.
- vstrlist_index (this , icomponent)
-
- integer , intent(in) :: icomponent
-
Returns a new vstring by getting the vstring at the given index icomponent
in the list.
Generates an error if the given index icomponent does not exist, that is,
is lower than 1 or greater than the number of strings in the list.
- vstrlist_append (this , string)
-
- type ( t_vstring ) , intent(in) :: string
-
Add the given vstring at the end of the current list.
- vstrlist_append (this , string)
-
- character(len=*) , intent(in) :: string
-
Add the given character(len=*) string at the end of the current list.
- vstrlist_append (this , list)
-
- type ( t_vstringlist ) , intent(in) :: list
-
Add the given list at the end of the current list.
- vstrlist_concat (this , string)
-
- type ( t_vstring ) , intent(in) :: string
-
Returns a new list by concatenating the current list to the given string.
- vstrlist_concat (this , string)
-
- character (len=*), intent(in) :: string
-
Returns a new list by concatenating the current list to the given character(len=*) string.
- vstrlist_concat (this , list)
-
- type ( t_vstringlist ) , intent(in) :: list
-
Returns a new list by concatenating the current list to the given list.
- vstrlist_insert (this , strindex , string)
-
- integer , intent (in) :: strindex
-
- type ( t_vstring ) , intent(in) :: string
-
Creates a new list by inserting the given string into the current list just
before the given index strindex.
- vstrlist_insert (this , strindex , string)
-
- integer , intent (in) :: strindex
-
- character (len=*), intent(in) :: string
-
Creates a new list by inserting the given character (len=*) string into the current list just
before the given index strindex.
- vstrlist_range (this , first , last)
-
- integer , intent (in) :: first
-
- integer , intent (in) :: last
-
Returns a new list by extracting items of index
from first and last (included).
- vstrlist_range (this , first , last)
-
- integer , intent (in) :: first
-
- integer , intent (in) :: last
-
Returns a new list by extracting items of index
from first and last (included).
- vstrlist_set (this , strindex , string)
-
- integer , intent (in) :: strindex
-
- type ( t_vstring ), intent(in) :: string
-
Set the vstring string at the given strindex in the list,
replacing the existing vstring by the new one.
- vstrlist_set (this , strindex , string)
-
- integer , intent (in) :: strindex
-
- character (len=*), intent(in) :: string
-
Set the character(len=*) string at the given strindex in the list,
replacing the existing vstring by the new one.
- vstrlist_split (this ?, splitChars?)
-
- type ( t_vstring ), intent(in), optional :: splitChars
-
Returns an list of vstrings whose elements are the components in the current string.
Returns a list of vstrings created by splitting string at each character that is in
the splitChars argument. Each element of the result array will consist of
the characters from string that lie between instances of the characters in
splitChars. The number of components is zero if string contains adjacent
characters in splitChars. If splitChars is an empty string then each character of string
becomes a separate element of the result list. SplitChars defaults to the
standard white-space characters (space, newline, carriage return and tab).
- vstrlist_split (this ?, splitChars?)
-
- character(len=*), intent(in), optional :: splitChars
-
Same as previous but with character(len=*) splitChars.
- vstrlist_join (this ?, joinString?)
-
- type ( t_vstring ), intent(in), optional :: joinString
-
Returns the string formed by joining all
of the elements of list together with joinString separating
each adjacent pair of elements.
The joinString argument defaults to a space character.
- vstrlist_join (this ?, joinString?)
-
- character(len=*), intent(in), optional :: joinString
-
Same as previous but with character(len=*) joinString.
- vstrlist_search (this pattern ?, first? ?, notmatch? ?, exact?)
-
- type ( t_vstring ) , intent(in) :: pattern
-
- integer , intent(in), optional :: first
-
- logical , intent(in), optional :: notmatch
-
- logical , intent(in), optional :: exact
-
This command searches the elements of list to see if one of them matches
pattern. If so, the command returns the index of the first matching element.
If not, the command returns 0.
If the optional argument first is provided, then the list is searched
starting at position first.
Default value of first is 1
If the optional argument notmatch is provided, this negates the sense
of the match, returning the index of the first non-matching value in the list.
Default value of notmatch is .false.
Set exact to .true. so that the list element must contain exactly the same string as pattern.
Default value of exact is .false.
- vstrlist_search (this pattern ?, first? ?, notmatch? ?, exact?)
-
- character (len=*) , intent(in) :: pattern
-
- integer , intent(in), optional :: first
-
- logical , intent(in), optional :: notmatch
-
- logical , intent(in), optional :: exact
-
Same as previous with character (len=*) pattern.
- vstrlist_lsearch (this pattern ?, first? ?, notmatch? ?, exact?)
-
- type ( t_vstring ) , intent(in) :: pattern
-
- integer , intent(in), optional :: first
-
- logical , intent(in), optional :: notmatch
-
- logical , intent(in), optional :: exact
-
- logical , intent(in), optional :: allitems
-
This command searches the elements of list to see if one of them matches
pattern. If so, the command returns the list of the first matching element.
If not, the command returns an empty list.
If the optional argument first is provided, then the list is searched
starting at position first.
Default value of first is 1
If the optional argument notmatch is provided, this negates the sense
of the match, returning the index of the first non-matching value in the list.
Default value of notmatch is .false.
Set exact to .true. so that the list element must contain exactly the same string as pattern.
Default value of exact is .false.
If allitems is provided and true, returns the list of all matching elements.
Default value of allitems is .false.
- vstrlist_lsearch (this pattern ?, first? ?, notmatch? ?, exact?)
-
- character (len=*) , intent(in) :: pattern
-
- integer , intent(in), optional :: first
-
- logical , intent(in), optional :: notmatch
-
- logical , intent(in), optional :: exact
-
- logical , intent(in), optional :: allitems
-
Same as previous with character (len=*) pattern.
- vstrlist_sort (this ?, increasing? ?, classtype? ?, unique?)
-
- logical , intent(in), optional :: increasing
-
- character(len=*), intent(in), optional :: classtype
-
- logical , intent(in), optional :: unique
-
This command sorts the elements of list and returns a new list in sorted order.
If increasing is provided and true or not provided, sort the list in increasing order
(``smallest'' items first).
If increasing is provided and false, sort the list in decreasing order (``largest'' items first).
Default value of increasing is true.
If classtype is provided, converts the items of the list into that class of data before comparing
the items. The possible values of classtype are :
- "ascii" : compare items as strings ( default )
- "integer" : convert strings into integer before comparing items
- "real" : convert strings into real before comparing items
- "dictionnary" : use dictionary-style comparison.
This is the same as "ascii" except case is ignored.
If classtype is not provided, the default value is "ascii".
If unique is provided and true, then only the last set of duplicate
elements found in the list will be retained. Note that duplicates are
determined relative to the comparison used in the sort.
Two items are considered the same if the comparison command returns 0.
- vstrlist_sort (this , command ?, unique?)
-
- integer function command
-
- logical , intent(in), optional :: unique
-
This command sorts the elements of list and returns a new list in sorted order.
The command is a function used as a comparison operator.
The command is expected to return -1, 0, or 1, depending on whether
string_a is lexicographically less than, equal to, or greater than string_b.
It is expected that the command has the following interface :
| |
interface
integer function command ( string_a , string_b )
use m_vstring, only : t_vstring
type(t_vstring), intent(in) :: string_a
type(t_vstring), intent(in) :: string_b
end function command
end interface
|
If unique is provided and true, then only the last set of duplicate
elements found in the list will be retained. Note that duplicates are
determined relative to the comparison used in the sort.
Two items are considered the same if the comparison command returns 0.
Refactor the component and use datastructures/vectors.f90
Copyright © 2008 Michael Baudin michael.baudin@gmail.com