# flibs/m_vstringlist(n) 1.0 "flibs"

## NAME

flibs/m_vstringlist - Processing string list

## TABLE OF CONTENTS

TABLE OF CONTENTS
SYNOPSIS
DESCRIPTION
OVERVIEW
Design
Preprocessing
METHODS
TODO
COPYRIGHT

## SYNOPSIS

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

## DESCRIPTION

This module provides OO services to manage lists of vstrings.

## OVERVIEW

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

### Design

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.

### Preprocessing

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.

## METHODS

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.

## TODO

Refactor the component and use datastructures/vectors.f90

## COPYRIGHT

Copyright © 2008 Michael Baudin michael.baudin@gmail.com