To: J3                                                     J3/19-196r3
From: Dan Nagle
Subject: edits for ISO_FORTRAN_STRINGS US03
Date: 2019-August-08

Reference: 18-007r1, 19-160



Introduction

At meeting 218, paper 19-160 was passed supporting specifications
of the Part 2 procedures in the main standard.  The edits in this paper
propose to add a new 16.10.3 following the 16.10.2 subclause describing
the ISO_FORTRAN_ENV intrinsic module.

However, there now appears to be little support for doing so.
Therefore, the previous revision of this paper proposed a straw vote:

1. Standardize only the SPLIT routine
2. Do nothing.
3. Undecided.

The result is 12-0-5, so work continues on only SPLIT.

The design presented here supports two use-cases.
One is where more flexibility is desired, and the words are to be
found one-by-one.  The other is where the string is to be split
all-at-once using the same set of separators.  This allows a high-level
object-in (the string) and object-out (the array of words).



SPLIT (STRING, WORD, SET [, SEPARATOR, BACK])

STRING   shall be of type CHARACTER. It is an INTENT(INOUT) argument.
         It shall be allocatable with deferred length.

WORD     shall be of type CHARACTER of the same kind as STRING.
         It is an INTENT(OUT) argument.  It shall be allocatable
         with deferred length.  It may be a scalar or
         or an allocatable array.

SET      shall be of type CHARACTER of the same kind as STRING.
         It is an INTENT(IN) argument.

SEPARATOR (optional) shall be of type CHARACTER of the same kind
         as STRING. It is an INTENT(OUT) argument.  It may be a scalar
         or an array.  It shall be allocatable
         with deferred length.  It shall be an array if and only
         if WORD is an array.

BACK (optional) shall be of type LOGICAL.
         It is an INTENT(IN) argument.

<Case (i):> When WORD is scalar, the effect of the procedure is
to divide STRING at the first occurrence of a character that is in SET.
The STRING is searched in the forward direction unless BACK is present
with the value true, in which case the search is in the backward
direction.  The characters passed over in the search are returned
in the argument WORD and the remainder of STRING, not including
the SEPARATOR character, is returned in the argument STRING. If
the argument SEPARATOR is present, the actual character found which
separates WORD from the remainder of STRING is returned
in SEPARATOR.
If no character from SET is found or SET is of zero length,
the whole STRING is returned in WORD,
STRING is returned as zero length,
and SEPARATOR (if present) is returned as zero length.


<Case (ii):> When WORD is an array, the effect of the procedure is
to divide STRING at every occurrence of a character that is in SET,
and WORD is given the length of the longest contiguous
set of characters passed over.
The STRING is searched in the forward direction unless BACK is present
with the value true, in which case the search is in the backward
direction.  The ith characters passed over in the search are returned
in the ith element of argument WORD and the STRING is unchanged. If
the argument SEPARATOR is present, the actual character found which
separates the ith element of WORD from the remainder of STRING is returned
in the ith element of SEPARATOR.
If no character from SET is found or SET is of zero length,
the whole STRING is returned in the first element of WORD,
STRING is returned as zero length,
and SEPARATOR (if present) is returned as zero length.


<<Examples.>>

With
CHARACTER( LEN= :), ALLOCATABLE :: STRING, WORD
CHARACTER( LEN= 2) :: SET = ','

STRING = 'first,second,third'

CALL SPLIT( STRING, WORD, SET)
PRINT *, STRING, WORD, SET

prints second,third first ,

With
CHARACTER( LEN= :), ALLOCATABLE :: STRING
CHARACTER( LEN= :), ALLOCATABLE, DIMENSION( :) :: WORD
CHARACTER( LEN= 2) :: SET = ',;'

STRING = 'first,second,third'

CALL SPLIT( STRING, WORD, SET)
PRINT *, STRING, WORD, SET

prints first,second,third first  second third  ,;