08-292
To: J3
From: Malcolm Cohen
Subject: Intrinsic procedure brief descriptions
Date: 2008 November 04
1. Introduction
A number of intrinsic procedures have a Description that is much more
detailed than necessary, containing information that really belongs in the
Result Value paragraph. At best this wastes space and makes the standard
harder to read, at worst it risks questions of interpretation when the
Description and Result Value don't agree.
These should be simplified.
2. Edits
The descriptions that should be changed appear both in Table 13.1 and in
the Description paragraph of each intrinsic. This paper lists the current
description and the proposed change. If not stated, the reason is that the
description in unnecessarily long; other reasons are given with "Comment:"
(and those reasons usually indicate technical flaws).
ACHAR
Old: Character in a specified position of the ASCII collating sequence.
It is the inverse of the IACHAR function.
Comment: The "inverse" is totally irrelevant.
New: Convert ASCII collating sequence index to character.
Alt: Convert ASCII code value to character type.
ADJUSTL
Old: Adjust to the left, removing leading blanks and inserting trailing
blanks.
New: Rotate string to remove leading blanks.
ADJUSTR
Old: Adjust to the right, removing trailing blanks and inserting leading
blanks.
New: Rotate string to remove trailing blanks.
ALL
Old: Logical conjunction of elements of MASK along dimension DIM.
Comment: Wrong because DIM is optional.
New: Reduce logical array by conjunction.
ALLOCATED
Old: True if and only if an allocatable variable is allocated.
New: Query allocation status.
ANY
Old: Logical inclusive disjunction of elements of MASK along dimension
DIM.
Comment: Wrong because DIM is optional.
New: Reduce logical array by inclusive disjunction.
Alt: Reduce logical array with .OR. operation.
ASSOCIATED
Old: True if and only if POINTER is associated or POINTER is associated
with TARGET.
Comment: Tooo long.
New: Query pointer association.
BESSEL_*
Consideration omitted, left up to 08-280rN.
BGE
Old: True if and only if I is bitwise greater than or equal to J.
New: Bitwise greater than or equal to.
BGT
Old: True if and only if I is bitwise greater than J.
New: Bitwise greater than.
BLE
Old: True if and only if I is bitwise less than or equal to J.
New: Bitwise less than or equal to.
BLT
Old: True if and only if I is bitwise less than J.
New: Bitwise less than.
BIT_SIZE
Old: Number of bits defined by the model of 13.3.
New: Number of bits in integer model.
BTEST
Old: True if and only if a specified bit of an integer value is one.
New: Test single bit in an integer.
CHAR
Old: Character in a given position of the processor collating sequence
associated with the specified kind type parameter. It is the
inverse of the ICHAR function.
Comment: Ridiculous.
New: Convert collating sequence index to character.
Alt: Convert code value to character type.
CO_LBOUND
Old: Lower cobounds or a specified lower cobound of a coarray.
New: Lower cobound(s) of a coarray.
CO_UBOUND
Old: Upper cobounds or a specified upper cobound of a coarray.
New: Upper cobound(s) of a coarray.
COUNT
Old: Number of true elements of MASK along dimension DIM.
Comment: Wrong because DIM is optional.
New: Reduce logical array by counting true values.
CSHIFT
Old: Circular shift on an array expression of rank one or circular shifts
on all the complete rank one sections along a given dimension of an
array expression of rank two or greater. Elements shifted out at
one end of a section are shifted in at the other end. Different
sections may be shifted by different amounts and in different
directions.
Comment: This is an essay, not a description.
New: Circular shift of the elements of an array.
DATE_AND_TIME
Old: Return data about the real-time clock and date in a form compatible
with the representations defined in ISO 8601:1988.
Comment: Confusing to use "real-time clock" both here and in SYSTEM_CLOCK
when they are not the same clock.
New: Return current date and time.
Note: Add "These forms are compatible with the representations defined in
ISO 8601:1988." to the beginning of Note 13.8 [341:13.7.44].
DBLE
Old: Conversion to double precision real type.
Comment: double precision is a kind, not a type.
New: Conversion to double precision real.
DIGITS
Old: Number of significant digits of a numeric model.
DOT_PRODUCT
Old: Dot-product multiplication of numeric or logical vectors.
Comment: And after crossing the Tower Bridge bridge,
we see the Tower of London tower.
New: Dot product of numeric or logical vectors.
EOSHIFT
Old: End-off shift on an array expression of rank one or end-off shifts
on all the complete rank-one sections along a given dimension of an
array expression of rank two or greater. Elements are shifted off
at one end of a section and copies of a boundary value are shifted
in at the other end. Different sections may have different boundary
values and may be shifted by different amounts and in different
directions.
Comment: Beyond self-parody.
New: End-off shift of the elements of an array.
EXECUTE_COMMAND_LINE
Old: Execute the command line specified by the string COMMAND.
New: Execute a command line.
EXPONENT
Old: Exponent part of the argument when represented as an extended model
number.
New: Exponent of floating-point number.
EXTENDS_TYPE_OF
Old: True if and only if the dynamic type of A is an extension of the
dynamic type of MOLD.
New: Compare dynamic types.
FINDLOC
Old: Location of the first element of ARRAY identified by MASK along
dimension DIM having a value equal to VALUE.
Comment: DIM and MASK are both optional.
New: Reduce array by locating a specific value.
FRACTION
Old: Fractional part of the extended model representation of the argument
value.
New: Fractional part of floating-point number.
GET_COMMAND
Old: Get the entire command by which the program was invoked.
Comment: Quite often, it does not do that.
New: Query program invocation command.
GET_COMMAND_ARGUMENT
Old: Get an argument from the command by which the program was invoked.
Comment: Quite often, it does not do that.
New: Query arguments from program invocation.
GET_ENVIRONMENT_VARIABLE
Old: Get the value of an environment variable.
New: Query environment variable.
IACHAR
Old: Position of a character in the ASCII collating sequence. This is
the inverse of the ACHAR function.
New: Convert character to ASCII collating sequence index.
Alt: Return ASCII code value for character.
IALL
Old: Bitwise AND of all the elements of ARRAY along dimension DIM
corresponding to the true elements of MASK.
Comment: Both DIM and MASK are optional.
New: Reduce array with bitwise AND.
IANY
Old: Bitwise OR of all the elements of ARRAY along dimension DIM
corresponding to the true elements of MASK.
Comment: Both DIM and MASK are optional.
New: Reduce array with bitwise OR.
ICHAR
Old: Position of a character in the processor collating sequence
associated with the kind type parameter of the character. This is
the inverse of the CHAR function.
New: Convert character to collating sequence index.
Alt: Return code value for character.
IMAGE_INDEX
Old: Index of the image corresponding to the cosubscripts SUB for
COARRAY.
New: Image index corresponding to the cosubscripts SUB for COARRAY.
INDEX
Old: Starting position of a substring within a string.
New: Search a string for a substring.
Alt: Search for a substring.
IPARITY
Old: Bitwise exclusive OR of all the elements of ARRAY along dimension
DIM corresponding to the true elements of MASK.
Comment: Both DIM and MASK are optional.
New: Reduce array with bitwise exclusive OR.
IS_CONTIGUOUS
Old: True if and only if an object is contiguous (5.3.7).
New: Test contiguity of an array (5.3.7).
IS_IOSTAT_END
Old: True if and only if a value indicates an end-of-file condition.
Comment: It's an IOSTAT= value, not just "a value".
New: Test IOSTAT value for end-of-file indication.
IS_IOSTAT_EOR
Old: True if and only if a value indicates an end-of-record condition.
Comment: It's an IOSTAT= value, not just "a value".
New: Test IOSTAT value for end-of-record indication.
LBOUND
Old: Lower bounds or a specified lower bound of an array.
New: Lower bound(s) of an array.
LGE
Old: True if and only if a string is lexically greater than or equal to
another string, based on the ASCII collating sequence.
New: Greater than or equal according to the ASCII collating sequence.
Alt: ASCII greater than or equal.
Al2: Compare strings using the ASCII collating sequence.
LGT
Old: True if and only if a string is lexically greater than another
string, based on the ASCII collating sequence.
New: Greater than according to the ASCII collating sequence.
Alt: ASCII greater than.
Al2: Compare strings using the ASCII collating sequence.
LLE
Old: True if and only if a string is lexically less than or equal to
another string, based on the ASCII collating sequence.
New: Less than or equal according to the ASCII collating sequence.
Alt: ASCII less than or equal.
Al2: Compare strings using the ASCII collating sequence.
LLT
Old: True if and only if a string is lexically less than another string,
based on the ASCII collating sequence.
New: Less than according to the ASCII collating sequence.
Alt: ASCII less than.
Al2: Compare strings using the ASCII collating sequence.
MATMUL
Old: Matrix product of numeric or logical matrices.
New: Matrix multiplication.
MAXLOC
Old: Location of an element of ARRAY along dimension DIM having the
maximum value of the elements identified by MASK.
Comment: DIM and MASK are both optional.
New: Reduce array by finding the maximum value.
Alt: Location of maximum value.
MAXVAL
Old: Maximum value of the elements of ARRAY along dimension DIM
corresponding to the true elements of MASK.
Comment: DIM and MASK are both optional.
New: Reduce array by maximum value.
MERGE
Old: Value of TSOURCE or FSOURCE according to the value of MASK.
Comment: Needless detail combined with vagueness.
New: Choose between two expression values.
MINEXPONENT
Old: Minimum (most negative) exponent of a real model.
Comment: "minimum" is sufficient - it's not required to be negative.
New: Minimum exponent of a real model.
MINLOC
Old: Location of an element of ARRAY along dimension DIM having the
minimum value of the elements identified by MASK.
Comment: Both DIM and MASK are optional.
New: Reduce array by finding the minimum value.
Alt: Location of minimum value.
MINVAL
Old: Minimum value of all the elements of ARRAY along dimension DIM
corresponding to true elements of MASK.
Comment: Both DIM and MASK are optional.
New: Reduce array by minimum value.
MOVE_ALLOC
Old: Move an allocation from one allocatable object to another.
New: Move an allocation.
MVBITS
Old: Copy a sequence of bits from one data object to another.
Comment: Wrong, this is allowed within a single object.
New: Copy a sequence of bits.
NEAREST
Old: Nearest different machine-representable number in a given
direction.
New: Adjacent machine-representable number.
PACK
Old: Array of rank one packed under the control of a mask.
Comment: The array being packed is not required to be of rank one,
that's the rank of the result.
New: Pack a masked array into a vector.
Alt: Pack an array into a vector.
PARITY
Old: True if and only if an odd number of values are true in MASK along
dimension DIM.
Comment: DIM is optional.
New: Reduce array by .NEQV..
Alt: Reduce array by logical nonequivalence.
PRESENT
Old: True if and only if an optional argument is present.
New: Query presence of optional argument.
PRODUCT
Old: Product of all the elements of ARRAY along dimension DIM
corresponding to the true elements of MASK.
Comment: Both DIM and MASK are optional.
New: Reduce array by multiplication.
RANDOM_NUMBER
Old: Generate one pseudorandom number or an array of pseudorandom
numbers.
New: Generate pseudorandom number(s).
RANDOM_SEED
Old: Restart or query the pseudorandom number generator used by
RANDOM_NUMBER.
New: Restart or query the pseudorandom number generator.
RANGE
Old: Decimal exponent range of the model representing integer or real
numbers with the same kind type parameter as the argument.
Comment: Inconsistent with PRECISION.
New: Decimal exponent range of a real model.
REPEAT
Old: Concatenation of several copies of a string.
New: Repeatedly concatenate a string.
RRSPACING
Old: Reciprocal of the relative spacing of model numbers near the
argument value.
New: Reciprocal of relative spacing of model numbers.
SAME_TYPE_AS
Old: True if and only if the dynamic type of A is the same as the
dynamic type of B.
New: Compare dynamic types.
Alt: Compare dynamic types for equality.
SCALE
Old: X*b**I where b is the base of the model representation of X.
New: Scale real number by a power of the base.
SCAN
Old: Position in a string of any one of the characters in a set of
characters.
New: Search for any one of a set of characters.
SELECTED_CHAR_KIND
Old: Value of the kind type parameter of the character set named by the
argument.
New: Select character kind type parameter value.
SELECTED_INT_KIND
Old: Value of the kind type parameter of an integer type that represents
all integer values $n$ with $-10^{\text{R}} < n < 10^{\text{R}}$.
New: Select integer kind type parameter value.
SELECTED_REAL_KIND
Old: Value of the kind type parameter of a real type with decimal
precision of at least P digits, a decimal exponent range of at least
R, and a radix of RADIX.
Comment: Why do we even need a Result Value paragraph?
New: Select real kind type parameter value.
SET_EXPONENT
Old: Number whose fractional part is the fractional part of the extended
model representation of X and whose exponent part is I.
New: Set the exponent of a floating-point number.
Alt: Construct number from a fraction and an exponent.
SIZE
Old: Extent of an array along a specified dimension or the total number
of elements in the array.
New: Size of an array or one dimension.
SPACING
Old: Absolute spacing of model numbers near the argument value.
New: Model number spacing.
SPREAD
Old: Array with rank that is one greater than SOURCE formed by
broadcasting SOURCE along a specified dimension.
New: Form higher-rank array by replication.
STORAGE_SIZE
Old: Storage size in bits that an array element of the same dynamic type
and type parameters of A would have.
New: Storage size in bits.
SUM
Old: Sum of all the elements of ARRAY along dimension DIM corresponding
to the true elements of MASK.
Comment: MASK is optional and DIM does not even exist in one form.
New: Reduce array by addition.
SYSTEM_CLOCK
Old: Return numeric data from a real-time clock.
New: Query real-time clock.
Alt: Query system clock.
THIS_IMAGE (the second one)
Old: A list of cosubscripts, or a single cosubscript.
New: Cosubscript(s) corresponding to this image.
TRANSFER
Old: Data object having a physical representation identical to that of
SOURCE but with the type and type parameters of MOLD.
Comment: Wrong - sometimes true, sometimes not.
New: Transfer physical representation.
TRIM
Old: Argument with trailing blank characters removed.
New: String without trailing blanks.
UBOUND
Old: Upper bounds of an array or a specified upper bound.
New: Upper bound(s) of an array.
UNPACK
Old: Array unpacked from an array of rank one under the control of a
mask.
New: Unpack a vector into an array.
VERIFY
Old: Position of a character in a string of characters that does not
appear in a given set of characters.
New: Search for a character not in a given set.
3. Additional edits
We have a whole subclause wittering on about MASK= arguments, but we don't
have anything for DIM arguments. Here is a suggestion, arising from the
consideration that I informally used "reduce" in the suggestions above
without describing what that meant.
[314:13.3-]
"13.2.4 Dim arguments and reduction functions
Some array intrinsic functions are ``reduction'' functions; that is, they
reduce the rank of an array by collapsing one dimension (or all
dimensions, usually producing a scalar result). These functions have an
optional DIM argument that, if present, specifies the dimension to be
reduced. The DIM argument of a reduction function is not permitted to be
an optional dummy argument.
The process of reducing a dimension usually combines the selected
elements with a simple operation such as addition or an intrinsic function
such as MAX, but more sophisticated reductions are also provided, e.g. by
COUNT and MAXLOC."
===END===