This is the mail archive of the
fortran@gcc.gnu.org
mailing list for the GNU Fortran project.
[fortran, doc, committed] Improve TRANSFER documentation.
- From: Brooks Moses <brooks dot moses at codesourcery dot com>
- To: fortran at gcc dot gnu dot org
- Cc: gcc-patches at gcc dot gnu dot org
- Date: Fri, 27 Apr 2007 13:17:48 -0700
- Subject: [fortran, doc, committed] Improve TRANSFER documentation.
The attached patch improves the documentation of the TRANSFER intrinsic,
as per Daniel Franke's recent request that someone else work on it. :)
Tested with "make pdf" and "make info" on i686-pc-linux-gnu, and
committed to both 4.2 and trunk.
With this, I believe that the 4.2 documentation is ready to ship. Many
thanks to Daniel for his recent efforts in getting all of the intrinsics
documented!
- Brooks
-----------------------------------------------------------------
2007-04-27 Brooks Moses <brooks.moses@codesourcery.com>
* intrinsic.texi (Transfer): Improve documentation.
-----------------------------------------------------------------
Index: intrinsic.texi
===================================================================
--- intrinsic.texi (revision 124230)
+++ intrinsic.texi (working copy)
@@ -9526,10 +9526,12 @@
@table @asis
@item @emph{Description}:
-Interprets the bit pattern of @var{SOURCE} as a variable of the
-same type and type parameters as @var{MOLD}.
+Interprets the bitwise representation of @var{SOURCE} in memory as if it
+is the representation of a variable or array of the same type and type
+parameters as @var{MOLD}.
-This is also known as @emph{casting} one type to another.
+This is approximately equivalent to the C concept of @emph{casting} one
+type to another.
@item @emph{Standard}:
F95 and later
@@ -9544,14 +9546,30 @@
@multitable @columnfractions .15 .70
@item @var{SOURCE} @tab Shall be a scalar or an array of any type.
@item @var{MOLD} @tab Shall be a scalar or an array of any type.
-@item @var{SIZE} @tab (Optional) shall be a scalar and of type
+@item @var{SIZE} @tab (Optional) shall be a scalar of type
@code{INTEGER}.
@end multitable
@item @emph{Return value}:
-The result has the same type as @var{MOLD} with the bit level
-representation of @var{SOURCE}.
+The result has the same type as @var{MOLD}, with the bit level
+representation of @var{SOURCE}. If @var{SIZE} is present, the result is
+a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent
+but @var{MOLD} is an array (of any size or shape), the result is a one-
+dimensional array of the minimum length needed to contain the entirety
+of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent
+and @var{MOLD} is a scalar, the result is a scalar.
+If the bitwise representation of the result is longer than that of
+@var{SOURCE}, then the leading bits of the result correspond to those of
+@var{SOURCE} and any trailing bits are filled arbitrarily.
+
+When the resulting bit representation does not correspond to a valid
+representation of a variable of the same type as @var{MOLD}, the results
+are undefined, and subsequent operations on the result cannot be
+guaranteed to produce sensible behavior. For example, it is possible to
+create @code{LOGICAL} variables for which @code{@var{VAR}} and
+@code{.NOT.@var{VAR}} both appear to be true.
+
@item @emph{Example}:
@smallexample
PROGRAM test_transfer