To: J3                                                     J3/25-135
From: generics
Subject: Edits for templates: TEMPLATE
Date: 2025-May-19
References: 25-109r2, 24-125r5, 24-126r4, 24-127r4

Introduction:
=============

This is the 1st of 6 papers that provide edits for the approved syntax
for templates:

   1. Templates
   2. Deferred arguments
   3. Instantiate
   4. Requirements
   5. Consistency constraints
   6. Miscellanous edits

Note that the clause numbering is merely suggestive.  The overall
ordering of template subclauses will change in future papers. For
example, the final order is likely to start with the TEMPLATE
construct introduced in the 3rd paper.


Section 1:
==========

* Insert the following text as a new clause.


tt Type-safe generic programming with templates

tt.1 The TEMPLATE construct

tt.1.1 Syntax for the TEMPLATE construct

A template contains declarations, specifications, and definitions that
are parameterized by deferred arguments. Public identifiers of a
template are made accessible to other scoping units by instantiation
of the template.  The accessible identifiers refer to specific
instances of the entities created by the instantiation.


Rtt10 <template> <<is>> <template-stmt>
                        [ <template-specification-part> ]
                        [ <template-subprogram-part> ]
                        <end-template-stmt>

Ctt28 (Rtt10) A <template> shall only appear in the <specification-part>
              of a main program or module.

Rtt11 <template-stmt> <<is>>
          TEMPLATE <template-name> ([<deferred-arg-name-list>])

Rtt12 <end-template-stmt> <<is>>  END TEMPLATE [<template-name>]


Ctt29 (Rtt12) If a <template-name> appears in the <end-template-stmt>,
              it shall be identical to the <template-name>
              specified in the <template-stmt>.

tt.1.2 Template specification part

Rtt13 <template-specification-part> <<is>>
          [ <use-stmt> ] ...
          [ <import-stmt> ] ...
          [ <template-declaration-construct> ] ...

Rtt14 <template-declaration-construct>
          <<is>> <template-specification-construct>
          <<or>> <deferred-arg-decl-stmt>
          <<or>> <requirement>
          <<or>> <template>

Rtt15 <template-specification-construct>
          <<is>> <access-stmt>
          <<or>> <derived-type-def>
          <<or>> <enum-def>
          <<or>> <enumeration-type-def>
          <<or>> <generic-stmt>
          <<or>> <instantiate-stmt>
          <<or>> <interface-block>
          <<or>> <intrinsic-stmt>
          <<or>> <procedure-declaration-stmt>
          <<or>> <type-declaration-stmt>

Ctt30 (Rtt15) If <type-declaration-stmt> is specified, PARAMETER shall
              appear as an <attr-spec>.

Ctt30+ (Rtt15) If <procedure-declaration-stmt> is specified, POINTER
               shall not appear.


{ The implicit mapping within a template scoping unit is the null mapping
  for all the letters - specified in the "misc edits" paper via a change
  to "8.7 Implicit statement". }

NOTE

    A template specification section cannot declare variables or procedure
    pointers.

tt.1.3 Template subprogram part

Rtt16 <template-subprogram-part> <<is>> <contains-stmt>
                                        [ <template-subprogram> ] ...

Rtt17 <template-subprogram>
          <<is>> <function-subprogram>
          <<or>> <subroutine-subprogram>
          <<or>> <templated-function-subprogram>
          <<or>> <templated-subroutine-subprogram>

tt.2 Templated procedures

A templated procedure is a template that defines a single
procedure which is accessible via instantiation.

{ Templated procedures are added to <internal-subprogram> and
  <module-subprogram> by the "misc edits" paper, and so can appear
  anywhere a normal procedure definition can appear. }

Rtt18 <templated-function-subprogram> <<is>>
          <templated-function-stmt>
          <templated-subprogram-specification-part>
          [<execution-part>]
          [<internal-subprogram-part>]
          <end-function-stmt>

Ctt31 (Rtt18) If a <function-name> appears in the <end-function-stmt>,
              it shall be identical to the <template-name>
              specified in the <templated-function-stmt>.

Rtt19 <templated-subroutine-subprogram> <<is>>
          <templated-subroutine-stmt>
          <templated-subprogram-specification-part>
          [<execution-part>]
          [<internal-subprogram-part>]
          <end-subroutine-stmt>

Ctt32 (Rtt19) If a <subroutine-name> appears in the <end-subroutine-stmt>,
              it shall be identical to the <template-name>
              specified in the <templated-subroutine-stmt>.

Ctt33 An internal templated procedure shall not contain an
      <internal-subprogram-part>.

Ctt34 The <internal-subprogram-part> of a templated procedure shall not
      contain a <templated-function-subprogram> or
      <templated-subroutine-subprogram>.


Rtt20 <templated-function-stmt> <<is>>
          [ <prefix> ] FUNCTION <template-name>
          ( <deferred-arg-name-list> ) ([<dummy-arg-list>])
          [<suffix>]

Rtt21 <templated-subroutine-stmt> <<is>>
         [ <prefix> ] SUBROUTINE <template-name>
         ( <deferred-arg-name-list> ) ([<dummy-arg-list>])
         [<proc-language-binding-spec>]

Rtt22 <templated-subprogram-specification-part> <<is>>
          [ <use-stmt> ] ...
          [ <import-stmt> ] ...
          [ <templated-subprogram-declaration-construct> ] ...

Rtt23 <templated-subprogram-declaration-construct>
          <<is>> <deferred-arg-decl-stmt>
          <<or>> <format-stmt>
          <<or>> <specification-construct>

Ctt35 In either <templated-function-stmt> or
      <templated-subroutine-stmt>, <prefix> shall include TEMPLATE.

tt.3 Restrictions on template definitions

Ctt36 A local variable or local procedure pointer declared anywhere
      within a template or templated subprogram shall not have the
      SAVE attribute.

Ctt37 A COMMON statement or EQUIVALENCE statement shall not appear
      anywhere within a template or templated subprogram.

Ctt38 A procedure referenced anywhere within a template or templated
      subprogram shall have an explicit interface.

NOTE 1

    Constraint Ctt38 expresses the notion of type-safety.  In particular,
    this allows a template implementation to be verified to be internally
    consistent.

NOTE 2

    Example of a TEMPLATE construct in a specification section.

    TEMPLATE iterate_tmpl(T, C, S)
       PRIVATE
       PUBLIC :: iterate
       DEFERRED TYPE :: T
       DEFERRED INTEGER, PARAMETER :: C
       DEFERRED INTERFACE
          SUBROUTINE S(x, i)
             TYPE(T), INTENT(INOUT) :: x
             INTEGER, INTENT(IN) :: i
          END SUBROUTINE
       END INTERFACE
    CONTAINS
       SUBROUTINE iterate(x)
          TYPE(T), INTENT(INOUT) :: x
          INTEGER :: i
          DO i = 1, C
             CALL S(x, i)
          END DO
       END SUBROUTINE iterate
    END TEMPLATE iterate_tmpl

    Alternative implementation for the above example using a templated
    procedure in a subprogram part.

    TEMPLATE SUBROUTINE iterate(T, C, S)(x)
       DEFERRED TYPE :: T
       DEFERRED INTEGER, PARAMETER :: C
       DEFERRED INTERFACE
          SUBROUTINE S(x, i)
             TYPE(T), INTENT(INOUT) :: x
             INTEGER, INTENT(IN) :: i
          END SUBROUTINE
       END INTERFACE

       TYPE(T), INTENT(INOUT) :: x
       INTEGER :: i
       DO i = 1, C
          CALL S(x, i)
       END DO

    END SUBROUTINE iterate


===END===