08-292r1
To: J3
From: David Muxworthy
Subject: Intrinsic procedure brief descriptions
Date: 2008 November 04
0. This is 292 as updated by discussion in /jor.
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. 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."
3. 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.
New: 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.
New: Reduce logical array by AND operation.
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.
New: Reduce logical array with OR operation.
ASSOCIATED
Old: True if and only if POINTER is associated or POINTER is associated
with TARGET.
New: Query pointer association status.
BESSEL_*
Consideration omitted, left up to 08-280rN.
/jor prefers the short form.
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 (13.3).
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.
New: 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.
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.
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.
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.
DOT_PRODUCT
Old: Dot-product multiplication of numeric or logical vectors.
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.
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: Query dynamic type for extension.
FINDLOC
Old: Location of the first element of ARRAY identified by MASK along
dimension DIM having a value equal to VALUE.
New: Location(s) of a specified 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.
New: Query program invocation command.
GET_COMMAND_ARGUMENT
Old: Get an argument from the command by which the program was invoked.
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: 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.
New: Reduce array with bitwise AND operation.
IANY
Old: Bitwise OR of all the elements of ARRAY along dimension DIM
corresponding to the true elements of MASK.
New: Reduce array with bitwise OR operation.
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: 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 for a substring.
IPARITY
Old: Bitwise exclusive OR of all the elements of ARRAY along dimension
DIM corresponding to the true elements of MASK.
New: Reduce array with bitwise exclusive OR operation.
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.
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.
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: ASCII greater than or equal.
LGT
Old: True if and only if a string is lexically greater than another
string, based on the ASCII collating sequence.
New: ASCII greater than.
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: ASCII less than or equal.
LLT
Old: True if and only if a string is lexically less than another string,
based on the ASCII collating sequence.
New: ASCII less than.
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.
New: Location(s) of maximum value of array.
MAXVAL
Old: Maximum value of the elements of ARRAY along dimension DIM
corresponding to the true elements of MASK.
New: Maximum value(s) of array.
MERGE
Old: Value of TSOURCE or FSOURCE according to the value of MASK.
New: Choose between two expression values.
MINEXPONENT
Old: Minimum (most negative) exponent of a real model.
New: Minimum exponent of a real model (13.4).
MINLOC
Old: Location of an element of ARRAY along dimension DIM having the
minimum value of the elements identified by MASK.
New: Reduce array by finding the minimum value.
Alt: Location(s) of minimum value of array.
MINVAL
Old: Minimum value of all the elements of ARRAY along dimension DIM
corresponding to true elements of MASK.
New: Minimum value(s) of array.
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.
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.
New: 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.
New: Reduce array with .NEQV. operation.
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.
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.
New: Decimal exponent range of a numeric model (13.4).
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: Query 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.
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.
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 extent.
SPACING
Old: Absolute spacing of model numbers near the argument value.
New: Spacing of model number (13.4).
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.
New: Reduce array by addition.
SYSTEM_CLOCK
Old: Return numeric data from a real-time clock.
New: 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.
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.
===END===