To: J3                                                     J3/19-197r1
From: Steve Lionel
Subject: Edits for C_F_STRPOINTER and F_C_STRING (US09)
Date: 2019-August-06

Keywords: CSTRING, FSTRING
Reference: 18-007r1, 18-252r2, N2165

Paper 18-252r2, passed by J3 at meeting 217, provided specifications
for two new intrinsic module procedures whose purpose is to
facilitate conversion between NUL-terminated C strings and
length-qualified Fortran strings. These implement the "CSTRING and
FSTRING" feature US09.

This paper proposes edits for this feature.

Edits to 18-007r1
-----------------

[xiii, Introduction]

Add to the bullet "Intrinsic procedures and modules", as appropriate:

"The procedures C_F_STRPOINTER and F_C_STRING have been added to
intrinsic module ISO_C_BINDING to assist in the use of NUL-terminated
strings."

[472:25+, 18.2.3.4+] (Procedures in the module)

Insert a new subclause after the entry for C_F_PROCPOINTER:

"
C_F_STRPOINTER (CSTRARRAY, FSTRPTR, NCHARS)
C_F_STRPOINTER (CSTRPTR, FSTRPTR, NCHARS)

Description. Associate a character pointer with a string

Class: Pure Subroutine

Arguments:

CSTRARRAY shall be a rank-1 character array of kind
C_CHAR, and with a length type parameter of 1. It is INTENT(IN) and
has the CONTIGUOUS and TARGET attributes.

CSTRPTR shall be a scalar of type C_PTR. It is an INTENT (IN) argument.
Its value shall be the C address of a sequence of characters of kind
C_CHAR. The value of CSTRPTR shall not be the C address of a Fortran
variable that does not have the TARGET attribute.

FSTRPTR shall be a deferred-length character pointer of kind C_CHAR.
It is INTENT(OUT). FSTRPTR becomes pointer associated with the storage
sequence S beginning with the first element of CSTRARRAY, or with the
storage sequence S for which the value of CSTRPTR is a C address.

Let N be the value of NCHARS if present, otherwise the extent of S.
The length type parameter of FSTRPTR becomes:
If there is an integer I in the range 1 <= I <= N such that
S(I:I) == CHAR(0_C_CHAR), then one less than the smallest such I;
otherwise N.

NCHARS (optional) shall be a nonnegative scalar integer. It is INTENT(IN).
NCHARS shall be present if CSTRARRAY is assumed-size, or if CSTRPTR
appears.
"

[473:35+, 18.2.3.7+]

Insert a new subclause after the entry for C_SIZEOF:

"F_C_STRING (STRING [, ASIS])

Description: Copy a string with appended NUL

Class: Transformational function

ASIS shall be a character scalar of default kind or of kind C_CHAR.

ASIS (optional) shall be a logical scalar.

Result characteristics: The result is of type character with
the same kind type parameter as STRING.

Result value:

Case (i): if ASIS is absent or has the value false, the value
of the result is the value of STRING with any trailing blanks
removed, and CHAR(0,KIND(STRING)) appended to the trimmed
value. The length type parameter is one greater than the length
of STRING less the number of trailing blanks in STRING.

Case (ii): if ASIS is present with the value true, the
value of the result is the value of STRING with CHAR(0,KIND(STRING))
appended. The length type parameter of the result is one greater
than the length of STRING.
"