StringiFor

StringiFor, Strings Fortran Manipulator, yet another strings Fortran module

A KISS pure Fortran library providing astrings (class) manipulator for modern (2003+) Fortran projects.

StringiFor is a pure Fortran (KISS) library providing a strings manipulator for modern Fortran projects;
StringiFor is Fortran 2003+ standard compliant;

StringiFor is OOP designed;
StringiFor is TDD designed;

StringiFor is a Free, Open Source Project.

Issues

Compiler Support

What is StringiFor?

Modern Fortran standards (2003+) have introduced a better support for characters variables, but Fortraners still do not have the power on dealing with strings of other more-rich-programmers, e.g. Pythoners. Allocatable deferred length character variables are now quantum-leap with respect the old inflexible Fortran characters, but it is still not enough for many Fortraners. Moreover, Fortran does not provide builtin methods for widely used strings manipulations offered by other languages, e.g. UPPER/lowercase transformation, tokenization, etc... StringiFor attempts to fill this lack.

Go to Top

Main features

StringiFor exposes only one class (OO-designed), the string type, that should be used as a more powerful string variable with respect a standard Fortran character variable. The main features of this class are:

seamless interchangeability with standard character variables, e.g. concatenation, IO, etc...;
handy builtin methods, e.g. split, search, basename, join, etc...;
low memory consumption: only one deferred length allocatable character member is stored, allowing for efficient memory allocation in array of strings, the elements of which can have different lengths;

safe: almost all methods are elemental or pure;
robust: the library is Test Driven Developed TDD, a comprehensive tests suite is provided.

Any feature request is welcome.

Go to Top

A Taste of StringiFor

StringiFor is very handy...

Basic IO
String manipulation
Numbers handling
Complex scenario

Basic IO

The class string IO is overloaded by defined write/read TBP. Moreover, dedicated methods and operators can be exploited for IO, e.g.

use stringifor
type(string) :: astring

astring = 'Hello World'
print "(A)", astring%chars() ! "chars" method returns a standard character variable
print "(DT)", astring        ! defined IO (in gfortran is available for GNU GCC >= 7.1)
print "(A)", astring//''     ! on-the-fly conversion to standard character by means of concatenation

String manipulation

The class string has many methods for a plethora of strings manipulations, e.g.

use stringifor
type(string) :: astring
type(string) :: strings(3)

astring = '0123456789'
print "(A)", astring%reverse()//'' ! print "9876543210"

astring = 'Hello World'
print "(A)", astring%replace(old='World', new='People')//'' ! print "Hello People"

astring = 'Hello World'
strings = astring%partition(sep='lo Wo')
print "(A)", 'Before sep: "'//strings(1)//'"' ! print "Hel"
print "(A)", 'Sep itself: "'//strings(2)//'"' ! print "lo Wo"
print "(A)", 'After sep:  "'//strings(3)//'"' ! print "rld"

strings(1) = 'one'
strings(2) = 'two'
strings(3) = 'three'
print "(A)", astring%join(strings)//''          ! print "oneHello WorldtwoHello Worldthree"
print "(A)", astring%join(strings, sep='-')//'' ! print "one-two-three"

astring = ' a StraNgE caSe var'
print "(A)", astring%camelcase()//'' ! print " AStrangeCaseVar"
print "(A)", astring%snakecase()//'' ! print " a_strange_case_var"
print "(A)", astring%startcase()//'' ! print " A Strange Case Var"

Numbers handling

StringiFor, by means of the portability environment library, PENF can handle numbers (reals and integers) effortless. The string/number casting (to/from and viceversa) is done by overloaded assignments (for all kinds of integers and reals). For convenience, StringiFor exposes the PENF number portable kind parameters.

use stringifor
type(string) :: astring

astring = 127 _I1P       ! "I1P" is the PENF kind for 1-byte-like integer.
print "(A)", astring//'' ! print "+127"

astring = 3.021e6_R4P    ! "R4P" is the PENF kind for 4-byte-like real.
print "(A)", astring//'' ! print "+0.302100E+07"

astring = "3.4e9" ! assign to a string without the necessity to define a real kind
if (astring%is_number()) then
  if (astring%is_real()) then
    print "(E13.6)", astring%to_number(kind=1._R4P) ! print " 0.340000E+10" using a 4-byte-like kind
  endif
endif

Complex scenario

StingiFor is developed to improve the poor Fortran people with daily strings-usage, however, also complex scenario is taken into account, e.g. file parsing, OS operations, etc...

use stringifor
type(string) :: astring

! OS like manipulation
astring = '/bar/foo.tar.bz2'
print "(A)", astring%basedir()//''                       ! print "/bar"
print "(A)", astring%basename()//''                      ! print "foo.tar.bz2"
print "(A)", astring%basename(extension='.tar')//''      ! print "foo"
print "(A)", astring%basename(strip_last_extension=.true.)//'' ! print "foo.tar"

! XML like tag parsing
astring = '<test> <first> hello </first> <first> not the first </first> </test>'
print "(A)", astring%search(tag_start='<first>', tag_end='</first>')//'' ! print "<first> hello </first>"

A naive CSV parser

This is just a provocation, but with StringiFor it is easy to develop a naive CSV parser. Let us assume we want to parse a cars-price database as the following one

Year, Make, Model, Description, Price
1997, Ford, E350   , ac abs moon, 3000.00
1999, Chevy, Venture "Extended Edition"  , , 4900.00
1999, Chevy, Venture "Extended Edition Very Large", , 5000.00

Well, parsing it and handling its cells values is very easy by means of StringiFor

use stringifor

implicit none
type(string)              :: csv            !< The CSV file as a single stream.
type(string), allocatable :: rows(:)        !< The CSV table rows.
type(string), allocatable :: columns(:)     !< The CSV table columns.
type(string), allocatable :: cells(:,:)     !< The CSV table cells.
type(string)              :: most_expensive !< The most expensive car.
real(R8P)                 :: highest_cost   !< The highest cost.
integer                   :: rows_number    !< The CSV file rows number.
integer                   :: columns_number !< The CSV file columns number.
integer                   :: r              !< Counter.

! parsing the just created CSV file: all done 9 statements!
call csv%read_file(file='cars.csv')              ! read the CSV file as a single stream
call csv%split(tokens=rows, sep=new_line('a'))   ! get the CSV file rows
rows_number = size(rows, dim=1)                  ! get the CSV file rows number
columns_number = rows(1)%count(',') + 1          ! get the CSV file columns number
allocate(cells(1:columns_number, 1:rows_number)) ! allocate the CSV file cells
do r=1, rows_number                              ! parse all cells
  call rows(r)%split(tokens=columns, sep=',')    ! get current columns
  cells(1:columns_number, r) = columns           ! save current columns into cells
enddo

! now you can do whatever with your parsed data
! print the table in markdown syntax
print "(A)", 'A markdown-formatted table'
print "(A)", ''
print "(A)", '|'//csv%join(array=cells(:, 1), sep='|')//'|'
print "(A)", '|'//repeat('----|', size(columns)) ! printing separators
do r=2, rows_number
  print "(A)", '|'//csv%join(array=cells(:, r), sep='|')//'|'
enddo
print "(A)", ''
! find the most expensive car
print "(A)", 'Searching for the most expensive car'
most_expensive = 'unknown'
highest_cost = -1._R8P
do r=2, rows_number
  if (cells(5, r)%to_number(kind=1._R8P)>=highest_cost) then
    highest_cost = cells(5, r)%to_number(kind=1._R8P)
    most_expensive = csv%join(array=[cells(2, r), cells(3, r)], sep=' ')
  endif
enddo
print "(A)", 'The most expensive car is : '//most_expensive

See the test program csv_naive_parser for a working example.

Obviously, this is a naive parser without any robustness, but it proves the usefulness of the StringiFor approach.

Go to Top

Copyrights

StringiFor is an open source project, it is distributed under a multi-licensing system:

for FOSS projects:
- GPL v3;
for closed source/commercial projects:
- BSD 2-Clause;
- BSD 3-Clause;
- MIT.

Anyone is interest to use, to develop or to contribute to StringiFor is welcome, feel free to select the license that best matches your soul!

More details can be found on wiki.

Go to Top

Download

StringiFor home is at https://github.com/szaghi/StringiFor. It uses git submodule to handle the third party dependencies. To download all the source files you can:

clone this repository (all dependencies are satisfied):
- git clone https://github.com/szaghi/StringiFor
- cd StringiFor
- git submodule update --init
download only the StringiFor sources, all other dependencies must be downloaded manually:
- download the latest master-branch archive:
  - wget https://github.com/szaghi/StringiFor/archive/master.zip
  - unzip StringiFor-master.zip
  - cd StringiFor-master
  - git submodule update --init
- download a release archive at https://github.com/szaghi/StringiFor/releases

Third Party dependencies

Currently StringiFor depends on:

The third party libraries are necessary for building StringiFor. StringiFor is constantly made up-to-date with third party libraries master branch or their latest release.

If you download a release of StringiFor manually (without git) you must download manually the above dependencies and place them into src/third_party sub-directory of the project root-tree.

Go to Top

Compilation

StringiFor is a modern Fortran project thus a modern Fortran compiler is need to compile the project. In the following table the support for some widely-used Fortran compilers is summarized.

Compiler Vendor Support	Notes
	full support
	full support
	not tested
	not tested
	not tested
	not tested

The library is modular, namely it exploits Fortran modules. As a consequence, there is compilation-cascade hierarchy to build the library. To correctly build the library the following approaches are supported

Build by means of FoBiS: full support;
Build by means of GNU Make: support for GNU Make is not provided, a Makefile is provided, but it is likely outdated and could not work as expected. Help for maintaining GNU Make support is strongly welcome, feel free to join this progect.
Build by means of CMake: support for CMake is not provide, some CMake support is provided by great users, but it could be outdated. Help for maintaining CMake support is strongly welcome, feel free to join this progect.

The FoBiS building support is the most complete and the only one officially supported by the author, as it is the one used for the developing StringiFor.

Build by means of FoBiS

A fobos file is provided to build the library by means of the Fortran Building System FoBiS.

Build all tests

Type

FoBiS.py build

After (a successuful) building a directory ./exe is created containing all the compiled tests that constitute the StringiFor regression-tests-suite, e.g.

→ FoBiS.py build
Builder options
Directories
  Building directory: "exe"
  Compiled-objects .o   directory: "exe/obj"
  Compiled-objects .mod directory: "exe/mod"
Compiler options
  Vendor: "gnu"
  Compiler command: "gfortran"
  Module directory switch: "-J"
  Compiling flags: "-c -frealloc-lhs -std=f2008 -fall-intrinsics -O2 -Dr16p"
  Linking flags: "-O2"
  Preprocessing flags: "-Dr16p"
  Coverage: False
  Profile: False
PreForM.py used: False
PreForM.py output directory: None
PreForM.py extensions processed: []

Building src/tests/is_real.f90
Compiling src/lib/penf.F90 serially
Compiling src/lib/string_t.F90 serially
Compiling src/lib/stringifor.F90 serially
Compiling src/tests/is_real.f90 serially
Linking exe/is_real
Target src/tests/is_real.f90 has been successfully built
Builder options
  Directories
    Building directory: "exe"
    Compiled-objects .o   directory: "exe/obj"
    Compiled-objects .mod directory: "exe/mod"
  Compiler options
    Vendor: "gnu"
    Compiler command: "gfortran"
    Module directory switch: "-J"
    Compiling flags: "-c -frealloc-lhs -std=f2008 -fall-intrinsics -O2 -Dr16p"
    Linking flags: "-O2"
    Preprocessing flags: "-Dr16p"
    Coverage: False
    Profile: False
  PreForM.py used: False
  PreForM.py output directory: None
  PreForM.py extensions processed: []

Building src/tests/slen.f90
Compiling src/tests/slen.f90 serially
...

→ tree -L 1 exe/
exe/
├── assignments
├── basename_dir
├── camelcase
├── capitalize
├── concatenation
├── equal
├── escape
├── extension
├── fill
...
├── swapcase
├── to_number
├── unique
└── upper_lower

Build the library

Type

# static-linked library by means of GNU gfortran
FoBiS.py build -mode stringifor-static-gnu

# shared-linked library by means of GNU gfortran
FoBiS.py build -mode stringifor-shared-gnu

# static-linked library by means of Intel Fortran
FoBiS.py build -mode stringifor-static-intel

# shared-linked library by means of Intel Fortran
FoBiS.py build -mode stringifor-shared-intel

The library will be built into the directory ./lib.

List other fobos modes

To list all fobos-provided modes type

→ FoBiS.py build -lmodes
The fobos file defines the following modes:
  - "tests-gnu"
  - "tests-gnu-debug"
  - "tests-intel"
  - "tests-intel-debug"
  - "stringifor-static-gnu"
  - "stringifor-shared-gnu"
  - "stringifor-static-intel"
  - "stringifor-shared-intel"

It is worth to note that the first mode is the one automatically called by FoBiS.py build.

Build by means of GNU Make

The provided makefile support only static-linked library building (not shared one) with both Intel Fortran Compiler and GNU gfortran, and it has two main building rules:

build the (static linked) library;
build the tests suite.

the GNU gfortran compiler is the default one, but the compiler used can be customized with COMPILER=#vendor switch.

To build the library type with the GNU gfortran compiler.

make

The library will be built into the directory ./lib/libstringifor.a.

To build the tests suite type

make TESTS=yes

The tests will be built into the directory ./exe.

If you want to use Intel Fortran Compiler add the switch COMPILER=intel to the above commands, i.e.

make COMPILER=intel # build only the library
make COMPILER=intel TESTS=yes # build the tests suite

Build by means of CMake

To be done.

Go to Top

Documentation

The StringiFor documentation is mainly contained into this file (it has its own wiki with some less important documents). Detailed documentation of the API is contained into the GitHub Pages that can also be created locally by means of ford tool.

Methods API

In the following all the methods of string are listed with a brief description of their aim. The hyperlinks bring you to the full API explained into the GH pages.

built-ins replacements

name	meaning
adjustl	adjustl replacement
adjustr	adjustr replacement
count	count replacement
index	index replacement
len	len replacement
len_trim	len_trim replacement
repeat	repeat replacement
scan	scan replacement
trim	trim replacement
verify	verify replacement

auxiliary methods

name	meaning
basedir	return the base directory name of a string containing a file name
basename	return the base file name of a string containing a file name
camelcase	return a string with all words capitalized without spaces
capitalize	return a string with its first character capitalized and the rest lowercased
chars	return the raw characters data
decode	decode string
encode	encode string
escape	escape backslashes (or custom escape character)
extension	return the extension of a string containing a file name
fill	pad string on the left (or right) with zeros (or other char) to fill width
free	free dynamic memory
insert	insert substring into string at a specified position
join	return a string that is a join of an array of strings or characters
lower	return a string with all lowercase characters
partition	split string at separator and return the 3 parts (before the separator and after)
read_file	read a file a single string stream
read_line	read line (record) from a connected unit
read_lines	read (all) lines (records) from a connected unit as a single ascii stream
replace	return a string with all occurrences of substring old replaced by new
reverse	return a reversed string
search	search for tagged record into string
slice	return the raw characters data sliced
snakecase	return a string with all words lowercase separated by _
split	return a list of substring in the string using sep as the delimiter string
startcase	return a string with all words capitalized, e.g. title case
strip	return a string with the leading and trailing characters removed
swapcase	return a string with uppercase chars converted to lowercase and vice versa
tempname	return a safe temporary name suitable for temporary file or directories
to_number	cast string to number
unescape	unescape double backslashes (or custom escaped character)
unique	reduce to one (unique) multiple occurrences of a substring into a string
upper	return a string with all uppercase characters
write_file	write a single string stream into file
write_line	write line (record) to a connected unit
write_lines	write lines (records) to a connected unit

inquire methods

name	meaning
end_with	return true if a string ends with a specified suffix
is_allocated	return true if the string is allocated
is_digit	return true if all characters in the string are digits
is_integer	return true if the string contains an integer
is_lower	return true if all characters in the string are lowercase
is_number	return true if the string contains a number (real or integer)
is_real	return true if the string contains an real
is_upper	return true if all characters in the string are uppercase
start_with	return true if a string starts with a specified prefix

operators

name	meaning
assignment	assignment of string from different inputs
//	concatenation resulting in characters for seamless integration
.cat.	concatenation resulting in `string`
==	equal operator
/=	not equal operator
<	lower than operator
<=	lower equal than operator
>=	greater equal than operator
>	greater than operator

IO

name	meaning
read(formatted)	formatted input
write(formatted)	formatted output
read(unformatted)	unformatted input
write(unformatted)	unformatted output

Go to Top

Comparison to other Approaches

The lack of Fortran support for strings manipulation has promoted different solutions in the past years. Following the classification of Clive Page [1] we can consider:

standard character type;
deferred-length allocatable character type (standard 2003+);
VARYING_STRING type (standard 90/95+) as defined in ISO/IEC 1539-2:2000 (Varying length character strings).

Let us compare StringiFor to the previous three approaches. In particular, let us consider Ian Harvey extension of VARYING_STRING, i.e. the aniso_varying_string [2].

Clive Page had pointed out the following issues, among the others:

fixed (at compile time) string length

character(len=3) :: astring ! further lengths different from 3 are not allowed

silent truncation on assignment

character(len=3) :: astring
astring = 'abcdefgh' ! silent trunctation at 'abc'

trim-cluttered code

character(len=99) :: astring
character(len=99) :: anotherstring
astring = 'abcdefgh'
anotherstring = trim(astring)//'ilmnopqrst' ! trim-cluttering is a necessity

handle significant trailing spaces

character(len=99) :: astring
character(len=99) :: anotherstring
astring = 'Hello ' ! for some reasons you want to keep these trailing white spaces
anotherstring = trim(astring)//'World' ! you need trim because
                                       ! len(astring)==len(anotherstring), but lost the significant
                                       ! trailing spaces...

different character definition

character         :: astring*10    ! old way
character(len=10) :: anotherstring ! new way

allocation of array of strings

character(len=10), allocatable :: astring(:)
allocate(astring(100)) ! all 100 elements of the array have 10 characters,
                       ! different lengths cannot be declared

initialization of array of strings

! the following is illegal
character(len=9), parameter :: day(7) = ['Monday',    &
                                         'Tuesday',   &
                                         'Wednesday', &
                                         'Thursday',  &
                                         'Friday',    &
                                         'Saturday',  &
                                         'Sunday']
! the following is legal, but cluttered by non significant trailing spaces
character(len=9), parameter :: day(7) = ['Monday   ', &
                                         'Tuesday  ', &
                                         'Wednesday', &
                                         'Thursday ', &
                                         'Friday   ', &
                                         'Saturday ', &
                                         'Sunday']

IO limitations for non standard character variables

character(len=99)             :: astring
character(len=:), allocatable :: anotherstring
type(varying_string)          :: yetanotherstring
! fully-simple support for standard character variables
astring = 'abcdefgh'
print*, astring
print "(A)", astring
read(10, *) astring
! partial-simple support for standard deferred length-length allocatable character variables
! care must be placed in input operation...
print*, anotherstring
print "(A)", anotherstring
read(10, *) anotherstring
! support depends on the implementation of the varying string type
print*, yetanotherstring
print "(DT)", yetanotherstring
read(10, *) yetanotherstring

substring notation (slice) for non standard character variables

character(len=99)             :: astring
character(len=:), allocatable :: anotherstring
type(varying_string)          :: yetanotherstring
astring = 'abcdefgh'
yetanotherstring = astring
anotherstring = astring(2:6)          ! allowed
anotherstring = yetanotherstring(2:6) ! not allowed

passing string to procedures expecting standard character argument is complicated

Analyzing the above issues we can agree that deferred-length allocatable character and aniso_varyng_string approaches address many of them, at the cost of introducing some oddies.

deferred-length allocatable character

This approaches addresses all the issues related to the fixed length limitation, e.g.

character(len=:), allocatable :: astring
character(len=:), allocatable :: anotherstring
astring = 'Hello '
anotherstring = astring//'World' ! trailing with spaces of astring correctly handled
                                 ! no need of trim

However, it has some limitations too. Aside the input operation, the most important (IMHO) are related to arrays of strings handling, e.g.

character(len=:), allocatable :: asetofstring(:)
allocate(character(len=99) :: asetofstring(10)) ! all 10 elements must have len=99

aniso_varying_string

Aniso_varying_string is an implemention of ISO/IEC 1539-2:2000 (Varying length character strings) developed by Ian Harvey that is internally based on a deferred-lenght allocatable character variable: it is essentially a derived type wrapping a deferred-lenght allocatable character. As a consequence, it has all the advantages of the deferred-length allocatable character approach. The wrapping approach addresses the arrays related issues, e.g.

type(varying_string), allocatable :: asetofstring(:)
allocate(asetofstring(10)) ! all 10 elements can have diffent lengths

Its major issues are related to IO operations: however, this is addressed by new Fortran support for defined IO for derived type that make more effortless the IO of such an object. The other main issue is the impossibility to use the standard slice notation to access to substring: aniso_varying_string addresses (partially) this issue by public-exposing the wrapped allocatable character of its implementations thus allowing the slicing of it, e.g.

type(varying_string) :: astring
astring = 'abcdefg'
print "(A)", astring%chars(2:3) ! print 'bc'

StringiFor

StringiFor shares the same philosophy of aniso_varying_string, thut it has the same pros and cons. However, StringiFor is an Object Oriented Designed class, thus it has some peculiariaties distinguishing it from aniso_varying_string, see StringiFor Peculiarities.

Comparison results

The following table summarizes the comparison analysis.

issue	standard character	deferred-length allocatable character	aniso_varying_string	StringiFor
fixed length	☁️	☀️	☀️	☀️
silent trunction	☁️	☀️	☀️	☀️
trim-clutter	☁️	☀️	☀️	☀️
significant trailing spaces	☁️	☀️	☀️	☀️
different string definition	☁️	☁️	☀️	☀️
array allocatation	☁️	☁️	☀️	☀️
array initialization	☁️	☁️	☀️	☀️
IO	☀️	☀️	⛅	⛅
substring (slice) notation	☀️	☀️	⛅	⛅
Fortran builtins	☀️	☀️	⛅	⛅

legend

symbol	meaning
☁️	bad or no support
⛅	partial support
☀️	good support

StringiFor Peculiarities

StringiFor publics an OOD class, the string object. This class is aimed to address all the issues of the standard character type, as ISO Varying String approaches do, but it is also designed to provide a features-rich string object as you can find on other languages like Python. As a matter of facts, the auxiliary methods added to the string object consitute a long list of new (for Fortraners) string-facilities, allowing you to handle strings effortless (cases-conversion, files-handling, encode/decode, numbers-casting, etc...), see the complete API. It is worth to note that StringiFor is a tentative to adopt an fully OOD thus all methods and operators are TBP defined: to use StringiFor you can import only the string type, allowing a sane and robust names space handling. Only in the case you want the Fortran builtins to accept a string instead of a standard character type, e.g. to use index(astring, 'c') seamless with both a type(string) :: astring and a character(99) :: astring, you must use all the StringiFor public objects, including the overloaded interfaces of the Fortran builtins.

References

[1] Improved String-handling in Fortran, Clive Page, October 2015.

[2] aniso_varying_string, Ian Harvey, 2016.

Go to Top

Name		Name	Last commit message	Last commit date
Latest commit History 268 Commits
.github/workflows		.github/workflows
cmake		cmake
doc		doc
scripts		scripts
src		src
.gitignore		.gitignore
.gitmodules		.gitmodules
CMakeLists.txt		CMakeLists.txt
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE.bsd-2.md		LICENSE.bsd-2.md
LICENSE.bsd-3.md		LICENSE.bsd-3.md
LICENSE.gpl3.md		LICENSE.gpl3.md
LICENSE.mit.md		LICENSE.mit.md
README.md		README.md
codecov.yml		codecov.yml
fobos		fobos
fpm.toml		fpm.toml
makefile		makefile

szaghi/StringiFor

Folders and files

Latest commit

History

Repository files navigation

StringiFor

StringiFor, Strings Fortran Manipulator, yet another strings Fortran module

Issues

Compiler Support

What is StringiFor?

Main features

A Taste of StringiFor

Basic IO

String manipulation

Numbers handling

Complex scenario

A naive CSV parser

Copyrights

Download

Third Party dependencies

Compilation

Build by means of FoBiS

Build all tests

Build the library

List other fobos modes

Build by means of GNU Make

Build by means of CMake

Documentation

Methods API

built-ins replacements

auxiliary methods

inquire methods

operators

IO

Comparison to other Approaches

deferred-length allocatable character

aniso_varying_string

StringiFor

Comparison results

legend

StringiFor Peculiarities

References

About

Topics

Resources

Stars

Watchers

Forks

Releases 8

Packages 0

Contributors 9

Languages

Packages