M_strings and associated files

Name

M_strings and M_strings__oop - Fortran modules for processing strings

Description

The M_strings(3fm) module is a collection of Fortran procedures that supplement the built-in intrinsic string routines. Routines for parsing, tokenizing, changing case, substituting new strings for substrings, locating strings with simple wildcard expressions, removing tabs and line terminators as well as other string manipulations are included.

M_strings_oop(3fm) is a companion module that provides an OOP interface to the M_strings module.

Note there are some procedures with overlapping function that were all initially gathered here that have varying performance and robustness that may be consolidated at some point.

Synopsis

grouping	page	description
INTRO:OOPS	M_strings__oop	OOP Fortran string module
INTRO	M_strings	Fortran string module
ARRAY	bundle	return up to twenty strings of arbitrary length as an array (LICENSE:PD)
ARRAY	c2s	convert C string pointer to Fortran character string (LICENSE:PD)
ARRAY	s2c	convert character variable to array of characters with last element set to null (LICENSE:PD)
ARRAY	switch	converts between CHARACTER scalar and array of single characters (LICENSE:PD)
BASE	base	convert whole number string in base [2-36] to string in alternate base [2-36] (LICENSE:PD)
BASE	base2	convert whole number to string in base 2 (LICENSE:PD)
BASE	codebase	convert whole number in base 10 to string in base [2-36] (LICENSE:PD)
BASE	decodebase	convert whole number string in base [2-36] to base 10 number (LICENSE:PD)
CASE	lower	changes a string to lowercase over specified range (LICENSE:PD)
CASE	lower_quoted	elemental function converts string to lowercase skipping strings quoted per Fortran syntax rules (LICENSE:PD)
CASE	upper	changes a string to uppercase (LICENSE:PD)
CASE	upper_quoted	elemental function converts string to uppercase skipping strings quoted per Fortran syntax rules (LICENSE:PD)
COMPARE	ends_with	test if string ends with specified suffix(es) (LICENSE:PD)
COMPARE	fortran_name	test if string meets criteria for being a fortran name (LICENSE:PD)
COMPARE	glob	compare given string for match to a pattern which may contain globbing wildcard characters (LICENSE:PD)
COMPARE	isalnum	test membership in subsets of ASCII set (LICENSE:PD)
COMPARE	isalpha	returns .true. if character is a letter and .false. otherwise (LICENSE:PD)
COMPARE	isascii	returns .true. if the character is in the range char(0) to char(256) (LICENSE:PD)
COMPARE	isblank	returns .true. if character is a blank character (space or horizontal tab). (LICENSE:PD)
COMPARE	iscntrl	returns .true. if character is a delete character or ordinary control character (LICENSE:PD)
COMPARE	isdigit	returns .true. if character is a digit (0, 1, ..., 9) and .false. otherwise (LICENSE:PD)
COMPARE	isgraph	returns .true. if character is a printable character except a space is considered non-printable (LICENSE:PD)
COMPARE	islower	returns .true. if character is a miniscule letter (a-z) (LICENSE:PD)
COMPARE	isprint	returns .true. if character is an ASCII printable character (LICENSE:PD)
COMPARE	ispunct	returns .true. if character is a printable punctuation character (LICENSE:PD)
COMPARE	isspace	returns .true. if character is a null, space, tab, carriage return, new line, vertical tab, or formfeed (LICENSE:PD)
COMPARE	isupper	returns .true. if character is an uppercase letter (A-Z) (LICENSE:PD)
COMPARE	isxdigit	returns .true. if character is a hexadecimal digit (0-9, a-f, or A-F). (LICENSE:PD)
COMPARE	longest_common_substring	function that returns the longest common substring of two strings.
DESCRIBE	describe	returns a string describing the name of a single character (LICENSE:PD)
DESCRIBE	edit_distance	returns a naive edit distance using the Levenshtein distance algorithm (LICENSE:PD)
EDITING	change	change old string to new string with a directive like a line editor (LICENSE:PD)
EDITING	join	append CHARACTER variable array into a single CHARACTER variable with specified separator (LICENSE:PD)
EDITING	modif	emulate the MODIFY command from the line editor XEDIT (LICENSE:PD)
EDITING	replace	function replaces one substring for another in string (LICENSE:PD)
EDITING	reverse	Return a string reversed (LICENSE:PD)
EDITING	squeeze	delete adjacent duplicate occurrences of a character from a string (LICENSE:PD)
EDITING	substitute	subroutine globally substitutes one substring for another in string (LICENSE:PD)
EDITING	transliterate	replace characters from old set with new set (LICENSE:PD)
ENCODE	decode_base64	decode data from base64 encoding as defined in RFC-4648 (LICENSE:MIT)
ENCODE	encode_base64	encode data using base64 encoding as defined in RFC-4648 (LICENSE:MIT)
ENCODE	percent_decode	percent-decode strings and character arrays (LICENSE:ISC)
ENCODE	percent_encode	percent-encode strings and character arrays (LICENSE:PD)
ENCODE	rotate13	apply trivial ROT13 encryption to a string (LICENSE:PD)
LENGTH	cpad	convert to a cropped string and then centers the string to specified length (LICENSE:PD)
LENGTH	len_white	get length of string trimmed of whitespace. (LICENSE:PD)
LENGTH	lenset	return string trimmed or padded to specified length (LICENSE:PD)
LENGTH	lpad	convert to a cropped string and then blank-pad on the left to requested length (LICENSE:PD)
LENGTH	merge_str	pads strings to same length and then calls MERGE(3f) (LICENSE:PD)
LENGTH	pad	return string padded to at least specified length (LICENSE:PD)
LENGTH	rpad	convert to a string and pad on the right to requested length (LICENSE:PD)
LENGTH	stretch	return string padded to at least specified length (LICENSE:PD)
LENGTH	zpad	pad a string on the left with zeros to specified length (LICENSE:PD)
NONALPHA	dilate	function to expand tab characters (LICENSE:PD)
NONALPHA	expand	expand C-like escape sequences (LICENSE:PD)
NONALPHA	noesc	convert non-printable characters to a space (LICENSE:PD)
NONALPHA	notabs	expand tab characters (LICENSE:PD)
NONALPHA	visible	expand a string to control and meta-control representations (LICENSE:PD)
NUMERIC	listout	expand a list of numbers where negative numbers denote range ends (1 -10 means 1 thru 10) (LICENSE:PD)
QUOTES	matching_delimiter	find position of matching delimiter (LICENSE:PD)
QUOTES	quote	add quotes to string as if written with list-directed output (LICENSE:PD)
QUOTES	unquote	remove quotes from string as if read with list-directed input (LICENSE:PD)
TOKENS	chomp	Tokenize a string, consuming it one token per call (LICENSE:PD)
TOKENS	delim	parse a string and store tokens into an array (LICENSE:PD)
TOKENS	find_field	parse a string into tokens (LICENSE:MIT)
TOKENS	paragraph	break a long line into a paragraph (LICENSE:PD)
TOKENS	sep	function to parse string into an array using specified delimiters (LICENSE:PD)
TOKENS	slice	parse string into an array using specified delimiters (LICENSE:PD)
TOKENS	split	parse string into an array using specified delimiters (LICENSE:PD)
TOKENS	split2020	parse a string into tokens using proposed f2023 method (LICENSE:PD)
TOKENS	strtok	Tokenize a string (LICENSE:PD)
TYPE	atoi	function returns a 32-bit integer value from a string (LICENSE:PD)
TYPE	atol	function returns a 64-bit integer value from a string (LICENSE:PD)
TYPE	aton	function returns argument as a numeric value from a string (LICENSE:PD)
TYPE	dble	overloads DBLE(3f) so it can handle character arguments (LICENSE:PD)
TYPE	fmt	convert any intrinsic to a string using specified format (LICENSE:PD)
TYPE	getvals	read arbitrary number of REAL values from a character variable up to size of VALUES() array (LICENSE:PD)
TYPE	int	overloads INT(3f) so it can handle character arguments (LICENSE:PD)
TYPE	isnumber	determine if a string represents a number (LICENSE:PD)
TYPE	nint	overloads NINT(3f) so it can handle character arguments (LICENSE:PD)
TYPE	real	overloads REAL(3f) so it can handle character arguments (LICENSE:PD)
TYPE	s2v	function returns doubleprecision numeric value from a string (LICENSE:PD)
TYPE	s2vs	given a string representing numbers return a numeric array (LICENSE:PD)
TYPE	str	converts multiple values to a (CSV) string (LICENSE:PD)
TYPE	string_to_value	subroutine returns numeric value from string (LICENSE:PD)
TYPE	string_to_values	read a string representing numbers into a numeric array (LICENSE:PD)
TYPE	v2s	return numeric string from a numeric value (LICENSE:PD)
TYPE	value_to_string	return numeric string from a numeric value (LICENSE:PD)
WHITESPACE	adjustc	center text (LICENSE:PD)
WHITESPACE	clip	trim leading and trailing blanks or set of characters from a string (LICENSE:PD)
WHITESPACE	compact	converts contiguous whitespace to a single character (or nothing) (LICENSE:PD)
WHITESPACE	crop	trim leading and trailing blanks and control characters from a string (LICENSE:PD)
WHITESPACE	indent	count number of leading spaces in a string (LICENSE:PD)
WHITESPACE	nospace	remove all whitespace from input string (LICENSE:PD)

Intrinsics

The M_strings(3fm) module supplements and works in combination with the Fortran built-in intrinsics. Standard Fortran lets you access the characters in a string using ranges much like they are character arrays assignment, comparisons with standard operators, supports dynamically allocatable strings and supports concatenation using the // operator:

 adjustl             Left adjust a string
 adjustr             Right adjust a string
 index               Position of a substring within a string
 repeat              Repeated string concatenation
 scan                Scan a string for the presence of a set of characters
 trim                Remove trailing blank characters of a string
 verify              Scan a string for the absence of a set of characters
 len                 It returns the length of a character string
 achar               converts an integer into a character
 iachar              converts a character into an integer
 len_trim            finds length of string with trailing spaces ignored
 new_line            Newline character
 selected_char_kind  Choose character kind
 lge                 Lexical greater than or equal
 lgt                 Lexical greater than
 lle                 Lexical less than or equal
 llt                 Lexical less than

Download and Build with make(1)

Just download the github repository, enter the src/ directory and run make:

 git clone https://github.com/urbanjost/M_strings.git
 cd M_strings/src
 # change Makefile if not using one of the listed compilers

 # for gfortran
 make clean
 make F90=gfortran gfortran

 # for ifort
 make clean
 make F90=ifort ifort

 # for nvfortran
 make clean
 make F90=nvfortran nvfortran

 # optionally
 make test # run the unit tests
 make run  # run all the demo programs from the man-pages
 make help # see other developer options

This will compile the M_strings(3f) module and optionally build all the example programs from the document pages in the example/ sub-directory and run the unit tests.

Download and Build with fpm(1)

Alternatively, download the github repository and build it with fpm ( as described at Fortran Package Manager )

     git clone https://github.com/urbanjost/M_strings.git
     cd M_strings
     fpm build
     fpm test  # run unit tests

or just list it as a dependency in your fpm.toml project file.

     [dependencies]
     M_strings        = { git = "https://github.com/urbanjost/M_strings.git" ,tag="v1.0.1"}

Note that M_strings.f90 is registered at the fpm(1) registry

Documentation

User

There are descriptions of each procedures in the style of man-pages in three formats:

An index to the HTML versions of the man-pages.
A single page (that uses javascript) combining all the HTML descriptions of the man-pages for easy searching and printing: BOOK_M_strings.
man-page archives for installation on GNU/Linux, Unix and CygWin platforms:
- manpages.zip
- manpages.tgz
CHANGELOG provides a history of significant changes