Module_String_Procedures¶
Copyright 2024 IRD
This file is part of statpack.
statpack is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
statpack is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
You can find a copy of the GNU Lesser General Public License in the statpack/doc directory.
Authors: Pascal Terray (LOCEAN/IPSL, Paris, France)
MODULE EXPORTING ROUTINES AND PARAMETERS FOR STRING PROCESSING AND PRINTING.
LATEST REVISION : 12/03/2024
function ascii_is_upper ( c )¶
Purpose¶
This function tests if the character C is an upper case letter.
Arguments¶
- C (INPUT) character
- The character to test
Further Details¶
It uses the ASCII collating sequence.
function is_upper ( c )¶
Purpose¶
This function tests if the character C is an upper case letter.
Arguments¶
- C (INPUT) character
- The character to test
Further Details¶
It uses the underlying machine collating sequence.
function ascii_is_lower ( c )¶
Purpose¶
This function tests if the character C is a lower case letter.
Arguments¶
- C (INPUT) character
- The character to test
Further Details¶
It uses the ASCII collating sequence.
function is_lower ( c )¶
Purpose¶
This function tests if the character C is a lower case letter.
Arguments¶
- C (INPUT) character
- The character to test
Further Details¶
It uses the underlying machine collating sequence.
function ascii_is_alpha ( c )¶
Purpose¶
This function tests if the character C is a letter.
Arguments¶
- C (INPUT) character
- The character to test
Further Details¶
It uses the ASCII collating sequence.
function is_alpha ( c )¶
Purpose¶
This function tests if the character C is a letter.
Arguments¶
- C (INPUT) character
- The character to test
Further Details¶
It uses the underlying machine collating sequence.
function ascii_is_same ( c1, c2 )¶
Purpose¶
ascii_is_same tests if C1 is the same character as C2 regardless of case.
Arguments¶
- C1, C2 (INPUT) character
- The characters to test
Further Details¶
It uses the ASCII collating sequence.
function is_same ( c1, c2 )¶
Purpose¶
is_same tests if C1 is the same character as C2 regardless of case.
Arguments¶
- C1, C2 (INPUT) character
- The characters to test
Further Details¶
It uses the underlying machine collating sequence.
function ascii_is_digit ( c )¶
Purpose¶
This function tests if the character C is a digit.
Arguments¶
- C (INPUT) character
- The character to test
Further Details¶
It uses the ASCII collating sequence.
function is_digit ( c )¶
Purpose¶
This function tests if the character C is a digit.
Arguments¶
- C (INPUT) character
- The character to test
Further Details¶
It uses the underlying machine collating sequence.
function is_space ( c )¶
Purpose¶
This function tests if the character C is a space or a tabulation.
Arguments¶
- C (INPUT) character
- The character to test
function is_num ( string )¶
Purpose¶
This function tests if the character argument STRING contains a numerical value.
Arguments¶
- STRING (INPUT) character(len=*)
- The string to analyze.
Further Details¶
Specifically, IS_NUM returns:
- KCHR = 0_i1b if STRING is a non-numerical string
- KINT = 1_i1b if STRING is an integer
- KFIX = 2_i1b if STRING is a fixed real
- KEXP = 3_i1b if STRING is a real with exponent
Definitions of KCHR, KINT, KFIX and KEXP may be obtained from the host module Strings.
This function is adapted from:
- Olagnon, M., 1996:
- Traitement de donnees numeriques avec Fortran 90. Masson, 264 pages, Chapter 5.3.2, ISBN 2-225-85259-6.
function string_count ( string, letter )¶
Purpose¶
STRING_COUNT returns the number of occurences of the letter LETTER in the string STRING.
Comparison is case-sensitive and trailing blanks are ignored.
Arguments¶
- STRING (INPUT) character(len=*)
- The string input.
- LETTER (INPUT) character(len=1)
- The letter to compare against.
Further Details¶
The result is an integer of kind i4b.
function ascii_string_eq ( string1, string2 )¶
Purpose¶
ASCII_STRING_EQ tests if 2 strings are equal, ignoring case and trailing blanks.
Arguments¶
- STRING1, STRING2 (INPUT) character(len=*)
- The strings to test.
Further Details¶
It uses the ASCII collating sequence.
function string_eq ( string1, string2 )¶
Purpose¶
STRING_EQ tests if 2 strings are equal, ignoring case and trailing blanks.
Arguments¶
- STRING1, STRING2 (INPUT) character(len=*)
- The strings to test.
Further Details¶
It uses the underlying machine collating sequence.
function ascii_string_index ( string, list )¶
Purpose¶
ASCII_STRING_INDEX returns index of a string in a list of strings, or 0 if no match. Comparison is case-insensitive and trailing blanks are ignored.
Arguments¶
- STRING (INPUT) character(len=*)
- The string input.
- LIST (INPUT) character(len=*), dimension(:)
- The list to compare against.
Further Details¶
It uses the ASCII collating sequence.
The result is an integer of kind i4b.
function string_index ( string, list )¶
Purpose¶
STRING_INDEX returns index of a string in a list of strings, or 0 if no match. Comparison is case-insensitive and trailing blanks are ignored.
Arguments¶
- STRING (INPUT) character(len=*)
- The string input.
- LIST (INPUT) character(len=*), dimension(:)
- The list to compare against.
Further Details¶
It uses the underlying machine collating sequence.
The result is an integer of kind i4b.
function ascii_string_comp ( string1, string2 )¶
Purpose¶
ASCII_STRING_COMP compares 2 strings, ignoring case and trailing blanks. It returns:
- 0 if strings are equal,
- -1 if STRING1 < STRING2,
- +1 if STRING1 > STRING2.
Arguments¶
- STRING1, STRING2 (INPUT) character(len=*)
- The strings to test.
Further Details¶
It uses the ASCII collating sequence.
The result is an integer of kind i1b.
function string_comp ( string1, string2 )¶
Purpose¶
STRING_COMP compares 2 strings, ignoring case and trailing blanks. It returns:
- 0 if strings are equal,
- -1 if STRING1 < STRING2,
- +1 if STRING1 > STRING2.
Arguments¶
- STRING1, STRING2 (INPUT) character(len=*)
- The strings to test.
Further Details¶
It uses the underlying machine collating sequence.
The result is an integer of kind i1b.
subroutine ebc2asc ( ebc_str, asc_str, nchr )¶
Purpose¶
EBC2ASC translates the EBCDIC string EBC_STR into a ASCII string ASC_STR.
Arguments¶
- EBC_STR (INPUT) character(len=*)
- The EBCDIC string to translate.
- ASC_STR (OUTPUT) character(len=*)
- The translated string (ASCII).
- NCHR (INPUT) integer(i4b)
- Number of characters to convert.
Further Details¶
EBC2ASC assumes that the storage unit for default characters is one byte and that the storage unit for integers is a given number of bytes.
Non ASCII characters are translated as the “null” character (achar(0)).
This subroutine is adapted from:
- Olagnon, M., 1996:
- Traitement de donnees numeriques avec Fortran 90. Masson, 264 pages, Chapter 5.2, ISBN 2-225-85259-6.
subroutine asc2ebc ( asc_str, ebc_str, nchr )¶
Purpose¶
ASC2EBC translates the ASCII string ASC_STR into a EBCDIC string EBC_STR .
Arguments¶
- ASC_STR (INPUT) character(len=*)
- The ASCII string to translate.
- EBC_STR (OUTPUT) character(len=*)
- The translated string (EBCDIC).
- NCHR (INPUT) integer(i4b)
- Number of characters to convert.
Further Details¶
ASC2EBC assumes that the storage unit for default characters is one byte and that the storage unit for integers is a given number of bytes.
For machines with extended ASCII characters set or machines returning values greater than 127 for intrinsic function IACHAR(), ASC2EBC assumes that characters “c” with IACHAR(c)>127 are the same as ACHAR(IACHAR(c)-128).
This subroutine is adapted from:
- Olagnon, M., 1996:
- Traitement de donnees numeriques avec Fortran 90. Masson, 264 pages, Chapter 5.2, ISBN 2-225-85259-6.
function ascii_to_upper ( c )¶
Purpose¶
This function converts the character C to upper case.
Arguments¶
C (INPUT) character
Further Details¶
All non-alphabetic characters are left unchanged. It uses the ASCII collating sequence.
function to_upper ( c )¶
Purpose¶
This function converts the character C to upper case.
Arguments¶
C (INPUT) character
Further Details¶
All non-alphabetic characters are left unchanged. It uses the underlying machine collating sequence.
function ascii_to_lower ( c )¶
Purpose¶
This function converts the character C to lower case.
Arguments¶
C (INPUT) character
Further Details¶
All non-alphabetic characters are left unchanged. It uses the ASCII collating sequence.
function to_lower ( c )¶
Purpose¶
This function converts the character C to lower case.
Arguments¶
C (INPUT) character
Further Details¶
All non-alphabetic characters are left unchanged. It uses the underlying machine collating sequence.
subroutine ascii_case_change ( string, type )¶
Purpose¶
This converts each lower case alphabetic letter in STRING to upper case, or vice versa.
Arguments¶
- STRING (INPUT/OUTPUT) character(len=*)
- The string to convert
- TYPE (INPUT/OUTPUT) integer(i1b)
Define the conversion. Specifically, if:
- TYPE = 1_i1b = TOUPPER, conversion is lower to upper
- TYPE = 2_i1b = TOLOWER, conversion is upper to lower
- TYPE = 3_i1b = CAPITALIZE, use upper for first letter; lower for rest
Definitions of TOUPPER, TOLOWER and CAPITALIZE may be obtained from the host module Strings.
Further Details¶
All non-alphabetic characters are left unchanged. It uses the ASCII collating sequence.
subroutine case_change ( string, type )¶
Purpose¶
This converts each lower case alphabetic letter in STRING to upper case, or vice versa.
Arguments¶
- string (INPUT/OUTPUT) character(len=*)
- The string to convert
- TYPE (INPUT/OUTPUT) integer(i1b)
Define the conversion. Specifically, if:
- TYPE = 1_i1b = TOUPPER, conversion is lower to upper
- TYPE = 2_i1b = TOLOWER, conversion is upper to lower
- TYPE = 3_i1b = CAPITALIZE, use upper for first letter; lower for rest
Definitions of TOUPPER, TOLOWER and CAPITALIZE may be obtained from the host module Strings.
Further Details¶
All non-alphabetic characters are left unchanged. It uses the underlying machine collating sequence.
subroutine mid_shift ( string, from, to, number )¶
Purpose¶
This routine performs a shift of characters within STRING. The number of characters shifted is NUMBER and they are shifted so that the character in position FROM is moved to position TO. Characters in the TO position are overwritten. Blanks replace characters in the FROM position. Shifting may be left or right, and the FROM and TO positions may overlap. Care is taken not to alter or use any characters beyond the defined limits of STRING.
Arguments¶
- STRING (INPUT/OUTPUT) character(len=*)
- The string to modify.
- FROM, TO, NUMBER (INPUT/OUTPUT) integer(i4b)
- Parameters defining the shift.
subroutine center ( string )¶
Purpose¶
This routine shifts the nonblank characters of STRING so that there is a balance of blanks on left and right.
Arguments¶
- STRING (INPUT/OUTPUT) character(len=*)
- The string to center.
subroutine find_field ( string, istart, iend, delims, isearch )¶
Purpose¶
This routine returns the starting and ending positions of a delimitted field in STRING taking into account the set of delimitters stored in the string DELIMS.
Arguments¶
- STRING (INPUT) character(len=*)
- The string to analyze.
- ISTART (OUTPUT) integer(i4b)
- The starting position of the field.
- IEND (OUTPUT) integer(i4b)
- The ending position of the field.
- DELIMS (INPUT, OPTIONAL) character(len=*)
- The string containing the characters to be accepted as delimitters.
- ISEARCH (INPUT, OPTIONAL) integer(i4b)
- The starting position for searching for the field.
Further Details¶
If the optional argument DELIMS is absent, the default delimitter set is a blank. If the optional argument ISEARCH is absent, the starting position for searching for the field is the first character of STRING.
On return, if:
- ISTART=0, STRING is empty, i.e contains only delimitters or is the null string ;
- ISTART/=0, the delimitted field is STRING(ISTART:IEND).
function nbrchf ( jval )¶
Purpose¶
This function determines the number of characters (digits and sign) needed to represent the integer JVAL.
Arguments¶
- JVAL (INPUT) integer(i4b)
- The integer to edit.
Further Details¶
The result is an integer of kind i4b.
function nbrchf ( rval )¶
Purpose¶
This function determines the number of characters (digits and sign) needed to represent the integer part of RVAL.
Arguments¶
- RVAL (INPUT) real(stnd)
- The real to edit.
Further Details¶
The result is an integer of kind i4b.
function obt_fmt ( jval )¶
Purpose¶
This function determines the “(Iw)” format needed to edit the integer JVAL without excess blanks. The format is returned as a fixed length blank-padded string of 12 characters.
Arguments¶
- JVAL (INPUT) integer(i4b)
- The integer to edit.
Further Details¶
If there is an error, FMT_INT returns a “blank string”.
The result is character string of length 12.
function obt_fmt ( rval, d )¶
Purpose¶
This function determines the “(Fw.d)” format needed to edit the real RVAL without excess blanks. The format is returned as a fixed length blank-padded string of 22 characters.
Arguments¶
- RVAL (INPUT) real(stnd)
- The real to edit.
- D (INPUT, OPTIONAL) integer(i4b)
- The desired number of decimal digits after the decimal point.
Further Details¶
If the optional parameter D is absent, the format returns by this function will edit the real RVAL with five decimals digits after the decimal point.
If there is an error, FMT_REAL returns a “blank” string.
The result is character string of length 22.
subroutine val_to_string ( jval, string, nchar )¶
Purpose¶
This function converts an integer to a string. The value is returned left adjusted in the string.
Arguments¶
- JVAL (INPUT) integer(i4b)
- The integer to convert.
- STRING (OUTPUT) character(len=*)
- The string.
- NCHAR (OUTPUT) integer(i4b)
- Number of characters used or needed to edit JVAL. The value is in STRING(1:NCHAR).
Further Details¶
If there is an error, INT_TO_STRING returns a string filled with ‘*’ and the right length of string needed to edit JVAL in NCHAR.
subroutine val_to_string ( rval, string, nchar, fmt, d )¶
Purpose¶
This function converts the real RVAL to a string with a given “Fw.d” or “Gw.d” format. The value is returned left adjusted in the string.
Arguments¶
- RVAL (INPUT) real(stnd)
- The real to convert.
- STRING (OUTPUT) character(len=*)
- The string.
- NCHAR (OUTPUT) integer(i4b)
- Number of characters used or needed to edit RVAL. The value is in STRING(1:NCHAR).
- FMT (INPUT,OPTIONAL) character
- “G” or “g” to use an G edit descriptor, an F edit descriptor is used for other values of FMT.
- D (INPUT, OPTIONAL) integer(i4b)
- Number of digits to appear after the decimal point in the output field for an F edit descriptor or number of significant digits to print for an G edit descriptor.
Further Details¶
If the optional parameter FMT is absent, an F edit descriptor is used by default.
If the optional parameter D is absent, five decimals digits will appear after the decimal point in the string for an F edit descriptor or five significant digits will be printed if an G edit descriptor is used.
If there is an error, REAL_TO_STRING returns a string filled with “*” and the right length of string needed to edit RVAL in NCHAR.
subroutine string_to_val ( string, kcode, fmt )¶
Purpose¶
This routine tests if the character argument STRING contains a numerical value and returns a format to read the string.
Arguments¶
- STRING (INPUT) character(len=*)
- The string to analyze.
- KCODE (OUTPUT) integer(i1b)
KCODE is equal to:
- KCHR = 0_i1b if STRING is a non-numerical string
- KINT = 1_i1b if STRING is an integer
- KFIX = 2_i1b if STRING is a fixed real
- KEXP = 3_i1b if STRING is a real with exponent
Definitions of KCHR, KINT, KFIX and KEXP may be obtained from the host module Strings.
- FMT (OUTPUT) character(len=14)
- The format to read the string.
Further Details¶
If there is an error, STRING_TO_VAL returns a format filled with blanks.