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

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 (STRARRAY, FSTRPTR, NCHARS)

Description. Associate a character pointer with a NUL-terminated string

Class: Pure Subroutine

Arguments:

STRARRAY shall be a rank-1 character array of default kind or kind
C_CHAR, and with a length type parameter of 1. It is INTENT(IN) and
has the TARGET attribute.

FSTRPTR shall be a deferred-length character pointer of default
kind or kind C_CHAR. It is INTENT(OUT). FSTRPTR becomes pointer
associated with the storage sequence S beginning with the first element
of STRARRAY. Let N be the value of NCHARS if present, otherwise the
extent of S. The length type parameter of FSTRPTR becomes:

Case(i): If there is an integer I in the range 1 <= I <= N such that
S(I:I) is equal to the value of C_NULL_CHAR from intrinsic module
ISO_C_BINDING, then one less than the smallest such I.

Case(ii): Otherwise, N.

NCHARS (optional) shall be a nonnegative scalar integer. It is INTENT(IN).
NCHARS shall be present if STRARRAY is assumed-size."

[473:35+, 18.2.3.7+]

Insert a new subclause after the entry for C_SIZEOF:

"F_C_STRING (STRING [, TRIM])

Description: NUL-terminated string copy

Class: Transformational function

STRING shall be a character scalar of default kind or of kind C_CHAR

TRIM (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 TRIM is absent or has the value true, the value
of the result is the value of STRING with any trailing blanks
removed, and a NUL character (C_NULL_CHAR) 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 TRIM is present with the value false, the
value of the result is the value of STRING with a NUL character
(C_NULL_CHAR) appended. The length type parameter of the result is one
greater than the length of STRING."