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