To: J3                                                     J3/25-135r1
From: generics
Subject: Edits for templates: TEMPLATE
Date: 2025-June-25
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.  Instantiation of a template
creates entities based on the definitions in the template, and those
with public identifiers are made accessible to the scoping unit in
which the instantiation appears.

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, module, or template.

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 can be instantiated via inline 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 At any level of nesting within a template or templated
      subprogram, entities that are not accessed by host or use
      association shall not have the SAVE attribute.

Ctt37 A COMMON statement or EQUIVALENCE statement shall not appear at
      any level of nesting within a template or templated subprogram,

Ctt38 A procedure referenced at any level of nesting 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.

    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

    An analogous example to the above using a templated procedure.

    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===