This is the mail archive of the
fortran@gcc.gnu.org
mailing list for the GNU Fortran project.
[fortran, documentation, patch] documenting more intrinsics
- From: Daniel Franke <franke dot daniel at gmail dot com>
- To: fortran at gcc dot gnu dot org
- Cc: gcc-patches at gcc dot gnu dot org
- Date: Sat, 14 Apr 2007 23:43:21 +0200
- Subject: [fortran, documentation, patch] documenting more intrinsics
- Dkim-signature: a=rsa-sha1; c=relaxed/relaxed; d=gmail.com; s=beta; h=domainkey-signature:received:received:from:to:subject:date:user-agent:cc:mime-version:content-type:message-id; b=OOkyZJqSwSV+xCG5Nd7g05ikAsTw7595MXDTn4VklhzBk4alhLZXaPLXbTgNTtEIy90qqxgiOTysbEarRDepphTdCSlmIXc6sqo9CqC8F8czFIDOVmah0Pje02hryaG5TXhj2ABtw/jkM7z38SeUDRqDF8LERqqPyNg+TZunkvA=
- Domainkey-signature: a=rsa-sha1; c=nofws; d=gmail.com; s=beta; h=received:from:to:subject:date:user-agent:cc:mime-version:content-type:message-id; b=bebEYbsqGDsEYI/Hj42TsnnyPOIBakTdzD9bumvC23GunqH/7/VG2oR3ZMehfYqKWqqf5v4n+Hzn+pLR0+TzxYK7Gu/+sNFcvY8v8dWQuIWs30Uc/ehiaej3fjPBNR+zjlM6g+QQEJMA+0D35mvi6DwdJdlXY5koj7vRbJm5Euc=
2007-04-14 Daniel Franke <franke.daniel@gmail.com>
* intrinsic.texi (NULL, PACK, PRESENT, REPEAT, SCAN, SHAPE, SIZE, TRANSPOSE,
TRIM, VERIFY): New.
(ADJUSTL, ADJUSTR, INDEX): Added cross references.
(INT, INT2, INT8, LONG): Enabled section header.
Tested info and dvi targets on i686-pc-linux-gnu.
Ok for 4.2 and trunk?
Daniel
P.S. After this, only PRODUCT, RESHAPE, SPACING, SPREAD, SUM, SYSTEM_CLOCK,
TRANSFER and UNPACK are left to be documented. Volunteers? :)
Index: intrinsic.texi
===================================================================
--- intrinsic.texi (revision 123760)
+++ intrinsic.texi (working copy)
@@ -194,7 +194,7 @@
* @code{PACK}: PACK, Pack an array into an array of rank one
* @code{PERROR}: PERROR, Print system error message
* @code{PRECISION}: PRECISION, Decimal precision of a real kind
-* @code{PRESENT}: PRESENT, Determine whether an optional argument is specified
+* @code{PRESENT}: PRESENT, Determine whether an optional dummy argument is specified
* @code{PRODUCT}: PRODUCT, Product of array elements
* @code{RADIX}: RADIX, Base of a data model
* @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
@@ -239,7 +239,7 @@
* @code{TINY}: TINY, Smallest positive number of a real kind
* @code{TRANSFER}: TRANSFER, Transfer bit patterns
* @code{TRANSPOSE}: TRANSPOSE, Transpose an array of rank two
-* @code{TRIM}: TRIM, Function to remove trailing blank characters of a string
+* @code{TRIM}: TRIM, Remove trailing blank characters of a string
* @code{TTYNAM}: TTYNAM, Get the name of a terminal device.
* @code{UBOUND}: UBOUND, Upper dimension bounds of an array
* @code{UMASK}: UMASK, Set the file creation mask
@@ -597,7 +597,7 @@
@node ADJUSTL
@section @code{ADJUSTL} --- Left adjust a string
@cindex @code{ADJUSTL} intrinsic
-@cindex adjust string
+@cindex string manipulation
@table @asis
@item @emph{Description}:
@@ -631,6 +631,9 @@
print *, str
end program test_adjustl
@end smallexample
+
+@item @emph{See also}:
+@ref{ADJUSTR}, @ref{TRIM}
@end table
@@ -638,7 +641,7 @@
@node ADJUSTR
@section @code{ADJUSTR} --- Right adjust a string
@cindex @code{ADJUSTR} intrinsic
-@cindex adjust string
+@cindex string manipulation
@table @asis
@item @emph{Description}:
@@ -672,6 +675,9 @@
print *, str
end program test_adjustr
@end smallexample
+
+@item @emph{See also}:
+@ref{ADJUSTL}, @ref{TRIM}
@end table
@@ -5052,6 +5058,7 @@
@node INDEX
@section @code{INDEX} --- Position of a substring within a string
@cindex @code{INDEX} intrinsic
+@cindex string manipulation
@table @asis
@item @emph{Description}:
@@ -5085,6 +5092,7 @@
kind.
@item @emph{See also}:
+@ref{SCAN}, @ref{VERIFY}
@end table
@@ -5150,7 +5158,6 @@
@item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab F77 and later
@end multitable
-@comment @item @emph{See also}:
@end table
@@ -5187,7 +5194,7 @@
@item @emph{Return value}:
The return value is a @code{INTEGER(2)} variable.
-@comment @item @emph{See also}:
+@item @emph{See also}:
@ref{INT}, @ref{INT8}, @ref{LONG}
@end table
@@ -5222,7 +5229,7 @@
@item @emph{Return value}:
The return value is a @code{INTEGER(8)} variable.
-@comment @item @emph{See also}:
+@item @emph{See also}:
@ref{INT}, @ref{INT2}, @ref{LONG}
@end table
@@ -6132,7 +6139,7 @@
@item @emph{Return value}:
The return value is a @code{INTEGER(4)} variable.
-@comment @item @emph{See also}:
+@item @emph{See also}:
@ref{INT}, @ref{INT2}, @ref{INT8}
@end table
@@ -7279,12 +7286,12 @@
@node NULL
@section @code{NULL} --- Function that returns an disassociated pointer
@cindex @code{NULL} intrinsic
-@cindex undocumented intrinsic
+@cindex pointer status
-Intrinsic implemented, documentation pending.
-
@table @asis
@item @emph{Description}:
+Returns a disassociated pointer.
+
@item @emph{Standard}:
F95 and later
@@ -7292,9 +7299,22 @@
Transformational function
@item @emph{Syntax}:
+@code{PTR => NULL([MOLD])}
+
@item @emph{Arguments}:
+@multitable @columnfractions .15 .70
+@item @var{MOLD} @tab (Optional) shall be a pointer of any association
+status and of any type.
+@end multitable
+
@item @emph{Return value}:
+A disassociated pointer.
+
@item @emph{Example}:
+@smallexample
+REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
+@end smallexample
+
@item @emph{See also}:
@ref{ASSOCIATED}
@end table
@@ -7354,12 +7374,14 @@
@node PACK
@section @code{PACK} --- Pack an array into an array of rank one
@cindex @code{PACK} intrinsic
-@cindex undocumented intrinsic
-Intrinsic implemented, documentation pending.
-
@table @asis
@item @emph{Description}:
+Pack an array of any rank into an array of rank one und control of a mask.
+
+At first, the elements whose @var{MASK} equals @code{TRUE} are packed into the
+result, then, if present, @var{VECTOR} elements are used
+
@item @emph{Standard}:
F95 and later
@@ -7367,10 +7389,46 @@
Transformational function
@item @emph{Syntax}:
+@code{RESULT = PACK(ARRAY, MASK[,VECTOR]}
+
@item @emph{Arguments}:
+@multitable @columnfractions .15 .70
+@item @var{ARRAY} @tab Shall be an array of any type, must not be scalar.
+@item @var{MASK} @tab Shall be of type @code{LOGICAL} and of the same
+size as @var{ARRAY}. Alternatively, it may be a scalar with value @code{TRUE}
+or @code{FALSE}.
+@item @var{VECTOR} @tab (Optional) shall be an array of the same type
+as @var{ARRAY} and of rank one. @var{VECTOR} shall have at least as
+many elements as there are true elements in @var{MASK}. If @var{MASK}
+is scalar, @var{VECTOR} shall have at least as many elements as there
+are in @var{ARRAY}.
+@end multitable
+
@item @emph{Return value}:
+The result is an array of rank one and the same type as that of @var{ARRAY}.
+If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
+number of @code{TRUE} values in @var{MASK} otherwise.
+
@item @emph{Example}:
-@item @emph{Specific names}:
+Gathering non-null elements from an array:
+@smallexample
+program test_pack_1
+ INTEGER :: m(6)
+ m = (/ 1 0 0 0 5 0 /)
+ IF (pack(m, m /= 0) /= (/ 1, 5 /)) CALL abort()
+end program
+@end smallexample
+
+@smallexample
+program test_pack_2
+ INTEGER :: m(4)
+ m = (/ 1 0 0 2 /)
+ IF (pack(m, m /= 0, (/ 0, 0, 3, 4 /)) /= (/ 1, 2, 3, 4 /)) THEN
+ CALL abort()
+ END IF
+end program
+@end smallexample
+
@item @emph{See also}:
@ref{UNPACK}
@end table
@@ -7450,14 +7508,13 @@
@node PRESENT
-@section @code{PRESENT} --- Determine whether an optional argument is specified
+@section @code{PRESENT} --- Determine whether an optional dummy argument is specified
@cindex @code{PRESENT} intrinsic
-@cindex undocumented intrinsic
-Intrinsic implemented, documentation pending.
-
@table @asis
@item @emph{Description}:
+Determine whether an optional dummy argument is present.
+
@item @emph{Standard}:
F95 and later
@@ -7465,10 +7522,30 @@
Inquiry function
@item @emph{Syntax}:
+@code{RESULT = PRESENT(A)}
+
@item @emph{Arguments}:
+@multitable @columnfractions .15 .70
+@item @var{A} @tab Shall be of any type and may be a pointer, scalar or array
+valued or a dummy procedure. It shall be the name of an optional dummy argument
+accessible within the current subroutine or function.
+@end multitable
+
@item @emph{Return value}:
+Returns either @code{TRUE} if the optional argument @var{A} is present, and
+@code{FALSE} otherwise.
+
@item @emph{Example}:
-@item @emph{See also}:
+@smallexample
+PROGRAM test_present
+ write(*,*) f(), f(42)
+CONTAINS
+ LOGICAL FUNCTION f(x)
+ INTEGER, INTENT(IN), OPTIONAL :: x
+ f = PRESENT(x)
+ END FUNCTION
+END PROGRAM
+@end smallexample
@end table
@@ -7866,10 +7943,10 @@
@cindex @code{REPEAT} intrinsic
@cindex string manipulation
-Intrinsic implemented, documentation pending.
-
@table @asis
@item @emph{Description}:
+Concatenate @var{NCOPIES} copies of a string.
+
@item @emph{Standard}:
F95 and later
@@ -7877,10 +7954,24 @@
Transformational function
@item @emph{Syntax}:
+@code{RESULT = REPEAT(STRING, NCOPIES)}
+
@item @emph{Arguments}:
+@multitable @columnfractions .15 .70
+@item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER(*)}.
+@item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER(*)}.
+@end multitable
+
@item @emph{Return value}:
+A new scalar of type @code{CHARACTER} build up from @var{NCOPIES} copies
+of @var{STRING}.
+
@item @emph{Example}:
-@item @emph{See also}:
+@smallexample
+program test_repeat
+ write(*,*) repeat("x", 5) ! "xxxxx"
+end program
+@end smallexample
@end table
@@ -7905,7 +7996,7 @@
@item @emph{Return value}:
@item @emph{Example}:
@item @emph{See also}:
-@ref{SHAPE}
+@ref{SHAPE}, @ref{SIZE}
@end table
@@ -8029,10 +8120,17 @@
@cindex @code{SCAN} intrinsic
@cindex string manipulation
-Intrinsic implemented, documentation pending.
-
@table @asis
@item @emph{Description}:
+Scans a @var{STRING} for any of the characters in a @var{SET}
+of characters.
+
+If @var{BACK} is either absent or equals @code{FALSE}, this function
+returns the position of the leftmost character of @var{STRING}, that is
+in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
+is returned. If no character of @var{SET} is found in @var{STRING}, the
+result is zero.
+
@item @emph{Standard}:
F95 and later
@@ -8040,10 +8138,30 @@
Elemental function
@item @emph{Syntax}:
+@code{RESULT = SCAN(STRING, SET[, BACK])}
+
@item @emph{Arguments}:
+@multitable @columnfractions .15 .70
+@item @var{STRING} @tab Shall be of type @code{CHARACTER(*)}.
+@item @var{SET} @tab Shall be of type @code{CHARACTER(*)}.
+@item @var{BACK} @tab (Optional) shall be of type logical.
+@end multitable
+
@item @emph{Return value}:
+The return value is of type @code{INTEGER} and of the default
+integer kind.
+
@item @emph{Example}:
+@smallexample
+PROGRAM test_scan
+ WRITE(*,*) SCAN("FORTRAN", "TR") ! 3
+ WRITE(*,*) SCAN("FORTRAN", "TR", .TRUE.) ! 5
+ WRITE(*,*) SCAN("FORTRAN", "C++") ! 0
+END PROGRAM
+@end smallexample
+
@item @emph{See also}:
+@ref{INDEX}, @ref{VERIFY}
@end table
@@ -8295,10 +8413,10 @@
@cindex @code{SHAPE} intrinsic
@cindex array manipulation
-Intrinsic implemented, documentation pending.
-
@table @asis
@item @emph{Description}:
+Determine the shape of an array.
+
@item @emph{Standard}:
F95 and later
@@ -8306,11 +8424,28 @@
Inquiry function
@item @emph{Syntax}:
+@code{RESULT = SHAPE(SOURCE)}
+
@item @emph{Arguments}:
+@multitable @columnfractions .15 .70
+@item @var{SHAPE} @tab Shall be an array or scalar of any type. Pointers
+must be associated, allocatable arrays must be allocated.
+@end multitable
+
@item @emph{Return value}:
+The shape of the @code{SOURCE}. If @code{SOURCE} is a scalar,
+the result is the rank one array of size zero.
+
@item @emph{Example}:
+@smallexample
+PROGRAM test_shape
+ WRITE(*,*) SHAPE((/ 1, 2 /)) ! 2
+ WRITE(*,*) SIZE(SHAPE(42)) ! 0
+END PROGRAM
+@end smallexample
+
@item @emph{See also}:
-@ref{RESHAPE}
+@ref{RESHAPE}, @ref{SIZE}
@end table
@@ -8532,10 +8667,11 @@
@cindex @code{SIZE} intrinsic
@cindex array manipulation
-Intrinsic implemented, documentation pending.
-
@table @asis
@item @emph{Description}:
+Determine the extent of @var{ARRAY} along a specified dimension @var{DIM}
+or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
+
@item @emph{Standard}:
F95 and later
@@ -8543,10 +8679,29 @@
Inquiry function
@item @emph{Syntax}:
+@code{RESULT = SIZE(ARRAY[, DIM])}
+
@item @emph{Arguments}:
+@multitable @columnfractions .15 .70
+@item @var{ARRAY} @tab Shall be an array of any type. Pointers
+must be associated, allocatable arrays must be allocated.
+@item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} and
+its value shall be in the range from 1 to n, n the rank of @var{ARRAY}.
+@end multitable
+
@item @emph{Return value}:
+The return value is of type @code{INTEGER} and of the default
+integer kind.
+
@item @emph{Example}:
+@smallexample
+PROGRAM test_size
+ WRITE(*,*) SIZE((/ 1, 2 /)) ! 2
+END PROGRAM
+@end smallexample
+
@item @emph{See also}:
+@ref{SHAPE}, @ref{RESHAPE}
@end table
@@ -9217,10 +9372,11 @@
@cindex @code{TRANSPOSE} intrinsic
@cindex matrix manipulation
-Intrinsic implemented, documentation pending.
-
@table @asis
@item @emph{Description}:
+Transpose an array of rank two. Element (i, j) of the result has the value
+@code{MATRIX(j, i)}, for all i, j.
+
@item @emph{Standard}:
F95 and later
@@ -9228,23 +9384,29 @@
Transformational function
@item @emph{Syntax}:
+@code{RESULT = TRANSPOSE(MATRIX)}
+
@item @emph{Arguments}:
+@multitable @columnfractions .15 .70
+@item @var{MATRIX} @tab Shall be of any type and have a rank of two.
+@end multitable
+
@item @emph{Return value}:
-@item @emph{Example}:
-@item @emph{See also}:
+The result has the the same type as @code{MATRIX} but shape (m,n) if
+@code{MATRIX} has shape (n,m).
@end table
@node TRIM
-@section @code{TRIM} --- Function to remove trailing blank characters of a string
+@section @code{TRIM} --- Remove trailing blank characters of a string
@cindex @code{TRIM} intrinsic
@cindex string manipulation
-Intrinsic implemented, documentation pending.
-
@table @asis
@item @emph{Description}:
+Remove trailing blank characters of a string.
+
@item @emph{Standard}:
F95 and later
@@ -9252,10 +9414,27 @@
Transformational function
@item @emph{Syntax}:
+@code{RESULT = TRIM(STRING)}
+
@item @emph{Arguments}:
+@multitable @columnfractions .15 .70
+@item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER(*)}.
+@end multitable
+
@item @emph{Return value}:
+A scalar of type @code{CHARACTER(*)} which length is that of @var{STRING}
+less the number of trailing blanks.
+
@item @emph{Example}:
+@smallexample
+PROGRAM test_trim
+ CHARACTER(len=10), PARAMETER :: s = "GFORTRAN"
+ WRITE(*,*) LEN(TRIM(s)) ! 8
+END PROGRAM
+@end smallexample
+
@item @emph{See also}:
+@ref{ADJUSTL}, @ref{ADJUSTR}
@end table
@@ -9445,10 +9624,16 @@
@cindex @code{VERIFY} intrinsic
@cindex string manipulation
-Intrinsic implemented, documentation pending.
-
@table @asis
@item @emph{Description}:
+Verifies that all the characters in a @var{SET} are present in a @var{STRING}.
+
+If @var{BACK} is either absent or equals @code{FALSE}, this function
+returns the position of the leftmost character of @var{STRING}, that is
+not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
+is returned. If all characters of @var{SET} are found in @var{STRING}, the
+result is zero.
+
@item @emph{Standard}:
F95 and later
@@ -9456,11 +9641,31 @@
Elemental function
@item @emph{Syntax}:
+@code{RESULT = VERFIY(STRING, SET[, BACK])}
+
@item @emph{Arguments}:
+@multitable @columnfractions .15 .70
+@item @var{STRING} @tab Shall be of type @code{CHARACTER(*)}.
+@item @var{SET} @tab Shall be of type @code{CHARACTER(*)}.
+@item @var{BACK} @tab (Optional) shall be of type logical.
+@end multitable
+
@item @emph{Return value}:
+The return value is of type @code{INTEGER} and of the default
+integer kind.
+
@item @emph{Example}:
-@item @emph{Specific names}:
+@smallexample
+PROGRAM test_verify
+ WRITE(*,*) VERIFY("FORTRAN", "FOR") ! 4
+ WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1
+ WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7
+ WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0
+END PROGRAM
+@end smallexample
+
@item @emph{See also}:
+@ref{SCAN}, @ref{INDEX}
@end table