This is the mail archive of the fortran@gcc.gnu.org mailing list for the GNU Fortran project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

[fortran, documentation, patch] documenting more intrinsics



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
 
 

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]