Skip to content

[Flang][Docs] Clean up flang/docs/IntrinsicTypes.md documentation #162184

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

[Flang][Docs] Clean up flang/docs/IntrinsicTypes.md documentation #162184

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ee8ce36
[Flang][Docs] Clean up flang/docs/IntrinsicTypes.md documentation
Oct 3, 2025
27c7dfa
Fix some whitespace issues.
Oct 3, 2025
9f3b030
Fix more whitespace issues.
Oct 3, 2025
2194d83
Hightlight some keywords and spell out `-fdefault-[real|integer]-<kin…
Oct 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
143 changes: 74 additions & 69 deletions flang/docs/IntrinsicTypes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,101 +14,106 @@ local:
---
```

Intrinsic types are integer, real, complex, character, and logical.
All intrinsic types have a kind type parameter called KIND,
Intrinsic types are `INTEGER`, `REAL`, `COMPLEX`, `CHARACTER`, and `LOGICAL`.
All intrinsic types have a kind type parameter called `KIND`,
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you know if the term "kind type parameter" is in common use/the language used in the standard? Just "kind parameter" seems clearer to me. But if the former is the convention (or in the official standard), we should prefer that.

Suggested change
All intrinsic types have a kind type parameter called `KIND`,
All intrinsic types have a kind parameter called `KIND`

which determines the representation method for the specified type.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
which determines the representation method for the specified type.
that determines the representation for the specified type.

The intrinsic type character also has a length type parameter called LEN,
The intrinsic type character also has a length type parameter called `LEN`,
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"length parameter" seems clearer to me than "length type parameter", but the same comment applies here as for "kind type parameter".

Suggested change
The intrinsic type character also has a length type parameter called `LEN`,
The intrinsic type `CHARACTER` also has a length parameter called `LEN`,

which determines the length of the character string.

The implementation of `CHARACTER` type in f18 is described
The implementation of the `CHARACTER` type in f18 is described
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It may be a good idea to switch to using flang instead of f18. The latter is the historic name of this compiler/project, but since the the official binary is also called "flang", so we probably should be consistent.

If you don't mind this being held up a little, I can bring it up at the flang call tomorrow (Wednesday, 8 Oct), to see if the community has any objections. Does that sound reasonable?

Suggested change
The implementation of the `CHARACTER` type in f18 is described
The implementation of the `CHARACTER` type in `flang` is described

in [Character.md](Character.md).

## Supported TYPES and KINDS

Here are the type and kind combinations supported in f18:

INTEGER(KIND=1) 8-bit two's-complement integer
INTEGER(KIND=2) 16-bit two's-complement integer
INTEGER(KIND=4) 32-bit two's-complement integer
INTEGER(KIND=8) 64-bit two's-complement integer
INTEGER(KIND=16) 128-bit two's-complement integer

REAL(KIND=2) 16-bit IEEE 754 binary16 (5e11m)
REAL(KIND=3) 16-bit upper half of 32-bit IEEE 754 binary32 (8e8m)
REAL(KIND=4) 32-bit IEEE 754 binary32 (8e24m)
REAL(KIND=8) 64-bit IEEE 754 binary64 (11e53m)
REAL(KIND=10) 80-bit extended precision with explicit normalization bit (15e64m)
REAL(KIND=16) 128-bit IEEE 754 binary128 (15e113m)

COMPLEX(KIND=2) Two 16-bit IEEE 754 binary16
COMPLEX(KIND=3) Two 16-bit upper half of 32-bit IEEE 754 binary32
COMPLEX(KIND=4) Two 32-bit IEEE 754 binary32
COMPLEX(KIND=8) Two 64-bit IEEE 754 binary64
COMPLEX(KIND=10) Two 80-bit extended precisions values
COMPLEX(KIND=16) Two 128-bit IEEE 754 binary128

No
[double-double
](https://en.wikipedia.org/wiki/Quadruple-precision_floating-point_format)
f18 supports the following type and kind combinations:

| Type | Description |
| :--: | :---------: |
| INTEGER(KIND=1) | 8-bit two's-complement integer |
| INTEGER(KIND=2) | 16-bit two's-complement integer |
| INTEGER(KIND=4) | 32-bit two's-complement integer |
| INTEGER(KIND=8) | 64-bit two's-complement integer |
| INTEGER(KIND=16) | 128-bit two's-complement integer |
| REAL(KIND=2) | 16-bit IEEE 754 binary16 (5e11m) |
| REAL(KIND=3) | 16-bit upper half of 32-bit IEEE 754 binary32 (8e8m) |
| REAL(KIND=4) | 32-bit IEEE 754 binary32 (8e24m) |
| REAL(KIND=8) | 64-bit IEEE 754 binary64 (11e53m) |
| REAL(KIND=10) | 80-bit extended precision with explicit normalization bit (15e64m) |
| REAL(KIND=16) | 128-bit IEEE 754 binary128 (15e113m) |
| COMPLEX(KIND=2) | Two 16-bit IEEE 754 binary16 |
| COMPLEX(KIND=3) | Two 16-bit upper half of 32-bit IEEE 754 binary32 |
| COMPLEX(KIND=4) | Two 32-bit IEEE 754 binary32 |
| COMPLEX(KIND=8) | Two 64-bit IEEE 754 binary64 |
| COMPLEX(KIND=10) | Two 80-bit extended precisions values |
| COMPLEX(KIND=16) | Two 128-bit IEEE 754 binary128 |
| LOGICAL(KIND=1) | 8-bit integer |
| LOGICAL(KIND=2) | 16-bit integer |
| LOGICAL(KIND=4) | 32-bit integer |
| LOGICAL(KIND=8) | 64-bit integer |

* No [double-double](https://en.wikipedia.org/wiki/Quadruple-precision_floating-point_format)
quad precision type is supported.
Comment on lines +54 to 55
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps a subheading like "NOTE" may be appropriate here to draw attention to the fact that the previous table is what is supported, but the following bullet points are not supported.

Suggested change
* No [double-double](https://en.wikipedia.org/wiki/Quadruple-precision_floating-point_format)
quad precision type is supported.
* [double-double](https://en.wikipedia.org/wiki/Quadruple-precision_floating-point_format)
quad precision type is not supported.

* No 128-bit logical support.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* No 128-bit logical support.
* 128-bit `LOGICAL` is not supported


LOGICAL(KIND=1) 8-bit integer
LOGICAL(KIND=2) 16-bit integer
LOGICAL(KIND=4) 32-bit integer
LOGICAL(KIND=8) 64-bit integer
### Defaults kinds
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
### Defaults kinds
### Default kinds


No 128-bit logical support.
f18 defaults to the following kinds for these types:

### Defaults kinds
* `INTEGER` 4
* `REAL` 4
* `COMPLEX` 4
* `DOUBLE PRECISION` 8
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

DOUBLE PRECISION is not in the table above. Is this intentional?

* `LOGICAL` 4

INTEGER 4
REAL 4
COMPLEX 4
DOUBLE PRECISION 8
LOGICAL 4
Modules compiled with different `-fdefault-real-<kind>` and
`-f-default-integer-<kind>` may be freely mixed. Module files encode the kind
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not sure that this is good message to send, in general. Mixing files compiled with different default kinds may cause problems for calls to subprograms without explicit interfaces.

value for every entity.

#### Modifying the default kind with default-real-8.
REAL 8
DOUBLE PRECISION 8
COMPLEX 8
#### Modifying the default kind with -fdefault-real-8:

#### Modifying the default kind with default-integer-8:
INTEGER 8
LOGICAL 8
* `REAL` 8
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider adding a sentence before these bullet points clarifying that the use of -fdefault-real-8 will only affect the default kinds for the following types.

* `DOUBLE PRECISION` 8
* `COMPLEX` 8

Modules compiled with different default-real and default-integer kinds
may be freely mixed.
Module files encode the kind value for every entity.
#### Modifying the default kind with -fdefault-integer-8:

## Representation of LOGICAL variables
* `INTEGER` 8
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider adding a sentence before these bullet points clarifying that the use of -fdefault-integer-8 will only affect the default kinds for the following types.

* `LOGICAL` 8

The default logical is `LOGICAL(KIND=4)`.
## Representation of LOGICAL variables

Logical literal constants with kind 1, 2, 4, and 8
share the following characteristics:
.TRUE. is represented as 1_kind
.FALSE. is represented as 0_kind
The Fortran standard specifies that a logical has two values, `.TRUE.` and
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The Fortran standard specifies that a logical has two values, `.TRUE.` and
The Fortran standard specifies that a `LOGICAL` has two values, `.TRUE.` and

`.FALSE.`, but does not specify their internal representation.

Tests for true is *integer value is not zero*.
Flang specifies that logical literal constants with `KIND=[1|2|4|8]` share the
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Flang specifies that logical literal constants with `KIND=[1|2|4|8]` share the
Flang specifies that `LOGICAL` literal constants with `KIND=[1|2|4|8]` share the

following characteristics:

The implementation matches gfortran.
* `.TRUE.` is `1_kind`.
* `.FALSE.` is `0_kind`.
* A true test is `<integer value> .NE. 0_kind`.

Programs should not use integer values in LOGICAL contexts or
use LOGICAL values to interface with other languages.
Programs should not use integer values in LOGICAL contexts or use LOGICAL values
to interface with other languages.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: "interoperate" seems more appropriate to me, but feel free to ignore this suggestion if you disagree.

Suggested change
to interface with other languages.
to interoperate with other languages.


### Representations of LOGICAL variables in other compilers
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
### Representations of LOGICAL variables in other compilers
### Representation of LOGICAL variables in other compilers


#### GNU gfortran

* `.TRUE.` is `1_kind`.
* `.FALSE.` is `0_kind`.
* A true test is `<integer value> .NE. 0_kind`.

#### Intel ifort / NVIDA nvfortran / PGI pgf90
.TRUE. is represented as -1_kind
.FALSE. is represented as 0_kind
Any other values result in undefined behavior.

Values with a low-bit set are treated as .TRUE..
Values with a low-bit clear are treated as .FALSE..
* `.TRUE.` is `-1_kind`.
* `.FALSE.` is `0_kind`.
* Any other values result in undefined behavior.
* Values with a low-bit set are treated as `.TRUE.`.
* Values with a low-bit clear are treated as `.FALSE.`.

#### IBM XLF
.TRUE. is represented as 1_kind
.FALSE. is represented as 0_kind

Values with a low-bit set are treated as .TRUE..
Values with a low-bit clear are treated as .FALSE..
* `.TRUE.` is `1_kind`.
* `.FALSE.` is `0_kind`.
* Values with a low-bit set are treated as `.TRUE.`.
* Values with a low-bit clear are treated as `.FALSE.`.
Loading