intdoc.in

gcc-2.95.3 Linux下最常用的C编译器

/* Copyright (C) 1997, 1999 Free Software Foundation, Inc.
 * This is part of the G77 manual.
 * For copying conditions, see the file g77.texi. */

/* This is the file containing the verbage for the
   intrinsics.  It consists of a data base built up
   via DEFDOC macros of the form:

   DEFDOC (IMP, SUMMARY, DESCRIPTION)

   IMP is the implementation keyword used in the intrin module.
   SUMMARY is the short summary to go in the "* Menu:" section
   of the Info document.  DESCRIPTION is the longer description
   to go in the documentation itself.

   Note that IMP is leveraged across multiple intrinsic names.

   To make for more accurate and consistent documentation,
   the translation made by intdoc.c of the text in SUMMARY
   and DESCRIPTION includes the special sequence

   @ARGNO@

   where ARGNO is a series of digits forming a number that
   is substituted by intdoc.c as follows:

   0     The initial-caps form of the intrinsic name (e.g. Float).
   1-98  The initial-caps form of the ARGNO'th argument.
   99    (SUMMARY only) a newline plus the appropriate # of spaces.

   Hope this info is enough to encourage people to feel free to
   add documentation to this file!

*/

#define ARCHAIC(upper,mixed) \
  "Archaic form of @code{" #upper "()} that is specific\n\
to one type for @var{@1@}.\n\
@xref{" #mixed " Intrinsic}.\n"

#define ARCHAIC_2nd(upper,mixed) \
  "Archaic form of @code{" #upper "()} that is specific\n\
to one type for @var{@2@}.\n\
@xref{" #mixed " Intrinsic}.\n"

#define ARCHAIC_2(upper,mixed) \
  "Archaic form of @code{" #upper "()} that is specific\n\
to one type for @var{@1@} and @var{@2@}.\n\
@xref{" #mixed " Intrinsic}.\n"

DEFDOC (ABS, "Absolute value.", "\
Returns the absolute value of @var{@1@}.

If @var{@1@} is type @code{COMPLEX}, the absolute
value is computed as:

@example
SQRT(REALPART(@var{@1@})**2, IMAGPART(@var{@1@})**2)
@end example

@noindent
Otherwise, it is computed by negating the @var{@1@} if
it is negative, or returning @var{@1@}.

@xref{Sign Intrinsic}, for how to explicitly
compute the positive or negative form of the absolute
value of an expression.
")

DEFDOC (CABS, "Absolute value (archaic).", ARCHAIC (ABS, Abs))

DEFDOC (DABS, "Absolute value (archaic).", ARCHAIC (ABS, Abs))

DEFDOC (IABS, "Absolute value (archaic).", ARCHAIC (ABS, Abs))

DEFDOC (CDABS, "Absolute value (archaic).", ARCHAIC (ABS, Abs))

DEFDOC (ACHAR, "ASCII character from code.", "\
Returns the ASCII character corresponding to the
code specified by @var{@1@}.

@xref{IAChar Intrinsic}, for the inverse of this function.

@xref{Char Intrinsic}, for the function corresponding
to the system's native character set.
")

DEFDOC (IACHAR, "ASCII code for character.", "\
Returns the code for the ASCII character in the
first character position of @var{@1@}.

@xref{AChar Intrinsic}, for the inverse of this function.

@xref{IChar Intrinsic}, for the function corresponding
to the system's native character set.
")

DEFDOC (CHAR, "Character from code.", "\
Returns the character corresponding to the
code specified by @var{@1@}, using the system's
native character set.

Because the system's native character set is used,
the correspondence between character and their codes
is not necessarily the same between GNU Fortran
implementations.

Note that no intrinsic exists to convert a numerical
value to a printable character string.
For example, there is no intrinsic that, given
an @code{INTEGER} or @code{REAL} argument with the
value @samp{154}, returns the @code{CHARACTER}
result @samp{'154'}.

Instead, you can use internal-file I/O to do this kind
of conversion.
For example:

@smallexample
INTEGER VALUE
CHARACTER*10 STRING
VALUE = 154
WRITE (STRING, '(I10)'), VALUE
PRINT *, STRING
END
@end smallexample

The above program, when run, prints:

@smallexample
        154
@end smallexample

@xref{IChar Intrinsic}, for the inverse of the @code{@0@} function.

@xref{AChar Intrinsic}, for the function corresponding
to the ASCII character set.
")

DEFDOC (ICHAR, "Code for character.", "\
Returns the code for the character in the
first character position of @var{@1@}.

Because the system's native character set is used,
the correspondence between character and their codes
is not necessarily the same between GNU Fortran
implementations.

Note that no intrinsic exists to convert a printable
character string to a numerical value.
For example, there is no intrinsic that, given
the @code{CHARACTER} value @samp{'154'}, returns an
@code{INTEGER} or @code{REAL} value with the value @samp{154}.

Instead, you can use internal-file I/O to do this kind
of conversion.
For example:

@smallexample
INTEGER VALUE
CHARACTER*10 STRING
STRING = '154'
READ (STRING, '(I10)'), VALUE
PRINT *, VALUE
END
@end smallexample

The above program, when run, prints:

@smallexample
 154
@end smallexample

@xref{Char Intrinsic}, for the inverse of the @code{@0@} function.

@xref{IAChar Intrinsic}, for the function corresponding
to the ASCII character set.
")

DEFDOC (ACOS, "Arc cosine.", "\
Returns the arc-cosine (inverse cosine) of @var{@1@}
in radians.

@xref{Cos Intrinsic}, for the inverse of this function.
")

DEFDOC (DACOS, "Arc cosine (archaic).", ARCHAIC (ACOS, ACos))

DEFDOC (AIMAG, "Convert/extract imaginary part of complex.", "\
Returns the (possibly converted) imaginary part of @var{@1@}.

Use of @code{@0@()} with an argument of a type
other than @code{COMPLEX(KIND=1)} is restricted to the following case:

@example
REAL(AIMAG(@1@))
@end example

@noindent
This expression converts the imaginary part of @1@ to
@code{REAL(KIND=1)}.

@xref{REAL() and AIMAG() of Complex}, for more information.
")

DEFDOC (DIMAG, "Convert/extract imaginary part of complex (archaic).", ARCHAIC (AIMAG, AImag))

DEFDOC (AINT, "Truncate to whole number.", "\
Returns @var{@1@} with the fractional portion of its
magnitude truncated and its sign preserved.
(Also called ``truncation towards zero''.)

@xref{ANInt Intrinsic}, for how to round to nearest
whole number.

@xref{Int Intrinsic}, for how to truncate and then convert
number to @code{INTEGER}.
")

DEFDOC (DINT, "Truncate to whole number (archaic).", ARCHAIC (AINT, AInt))

DEFDOC (INT, "Convert to @code{INTEGER} value truncated@99@to whole number.", "\
Returns @var{@1@} with the fractional portion of its
magnitude truncated and its sign preserved, converted
to type @code{INTEGER(KIND=1)}.

If @var{@1@} is type @code{COMPLEX}, its real part is
truncated and converted, and its imaginary part is disregarded.

@xref{NInt Intrinsic}, for how to convert, rounded to nearest
whole number.

@xref{AInt Intrinsic}, for how to truncate to whole number
without converting.
")

DEFDOC (IDINT, "Convert to @code{INTEGER} value truncated@99@to whole number (archaic).", ARCHAIC (INT, Int))

DEFDOC (ANINT, "Round to nearest whole number.", "\
Returns @var{@1@} with the fractional portion of its
magnitude eliminated by rounding to the nearest whole
number and with its sign preserved.

A fractional portion exactly equal to
@samp{.5} is rounded to the whole number that
is larger in magnitude.
(Also called ``Fortran round''.)

@xref{AInt Intrinsic}, for how to truncate to
whole number.

@xref{NInt Intrinsic}, for how to round and then convert
number to @code{INTEGER}.
")

DEFDOC (DNINT, "Round to nearest whole number (archaic).", ARCHAIC (ANINT, ANInt))

DEFDOC (NINT, "Convert to @code{INTEGER} value rounded@99@to nearest whole number.", "\
Returns @var{@1@} with the fractional portion of its
magnitude eliminated by rounding to the nearest whole
number and with its sign preserved, converted
to type @code{INTEGER(KIND=1)}.

If @var{@1@} is type @code{COMPLEX}, its real part is
rounded and converted.

A fractional portion exactly equal to
@samp{.5} is rounded to the whole number that
is larger in magnitude.
(Also called ``Fortran round''.)

@xref{Int Intrinsic}, for how to convert, truncate to
whole number.

@xref{ANInt Intrinsic}, for how to round to nearest whole number
without converting.
")

DEFDOC (IDNINT, "Convert to @code{INTEGER} value rounded@99@to nearest whole number (archaic).", ARCHAIC (NINT, NInt))

DEFDOC (LOG, "Natural logarithm.", "\
Returns the natural logarithm of @var{@1@}, which must
be greater than zero or, if type @code{COMPLEX}, must not
be zero.

@xref{Exp Intrinsic}, for the inverse of this function.

@xref{Log10 Intrinsic}, for the `common' (base-10) logarithm function.
")

DEFDOC (ALOG, "Natural logarithm (archaic).", ARCHAIC (LOG, Log))

DEFDOC (CLOG, "Natural logarithm (archaic).", ARCHAIC (LOG, Log))

DEFDOC (DLOG, "Natural logarithm (archaic).", ARCHAIC (LOG, Log))

DEFDOC (CDLOG, "Natural logarithm (archaic).", ARCHAIC (LOG, Log))

DEFDOC (LOG10, "Common logarithm.", "\
Returns the common logarithm (base 10) of @var{@1@}, which must
be greater than zero.

The inverse of this function is @samp{10. ** LOG10(@var{@1@})}.

@xref{Log Intrinsic}, for the natural logarithm function.
")

DEFDOC (ALOG10, "Common logarithm (archaic).", ARCHAIC (LOG10, Log10))

DEFDOC (DLOG10, "Common logarithm (archaic).", ARCHAIC (LOG10, Log10))

DEFDOC (MAX, "Maximum value.", "\
Returns the argument with the largest value.

@xref{Min Intrinsic}, for the opposite function.
")

DEFDOC (AMAX0, "Maximum value (archaic).", "\
Archaic form of @code{MAX()} that is specific
to one type for @var{@1@} and a different return type.
@xref{Max Intrinsic}.
")

DEFDOC (AMAX1, "Maximum value (archaic).", ARCHAIC (MAX, Max))

DEFDOC (DMAX1, "Maximum value (archaic).", ARCHAIC (MAX, Max))

DEFDOC (MAX0, "Maximum value (archaic).", ARCHAIC (MAX, Max))

DEFDOC (MAX1, "Maximum value (archaic).", "\
Archaic form of @code{MAX()} that is specific
to one type for @var{@1@} and a different return type.
@xref{Max Intrinsic}.
")

DEFDOC (MIN, "Minimum value.", "\
Returns the argument with the smallest value.

@xref{Max Intrinsic}, for the opposite function.
")

DEFDOC (AMIN0, "Minimum value (archaic).", "\
Archaic form of @code{MIN()} that is specific
to one type for @var{@1@} and a different return type.
@xref{Min Intrinsic}.
")

DEFDOC (AMIN1, "Minimum value (archaic).", ARCHAIC (MIN, Min))

DEFDOC (DMIN1, "Minimum value (archaic).", ARCHAIC (MIN, Min))

DEFDOC (MIN0, "Minimum value (archaic).", ARCHAIC (MIN, Min))

DEFDOC (MIN1, "Minimum value (archaic).", "\
Archaic form of @code{MIN()} that is specific
to one type for @var{@1@} and a different return type.
@xref{Min Intrinsic}.
")

DEFDOC (MOD, "Remainder.", "\
Returns remainder calculated as:

@smallexample
@var{@1@} - (INT(@var{@1@} / @var{@2@}) * @var{@2@})
@end smallexample

@var{@2@} must not be zero.
")

DEFDOC (AMOD, "Remainder (archaic).", ARCHAIC (MOD, Mod))

DEFDOC (DMOD, "Remainder (archaic).", ARCHAIC (MOD, Mod))

DEFDOC (AND, "Boolean AND.", "\
Returns value resulting from boolean AND of
pair of bits in each of @var{@1@} and @var{@2@}.
")

DEFDOC (IAND, "Boolean AND.", "\
Returns value resulting from boolean AND of
pair of bits in each of @var{@1@} and @var{@2@}.
")

DEFDOC (OR, "Boolean OR.", "\
Returns value resulting from boolean OR of
pair of bits in each of @var{@1@} and @var{@2@}.
")

DEFDOC (IOR, "Boolean OR.", "\
Returns value resulting from boolean OR of
pair of bits in each of @var{@1@} and @var{@2@}.
")

DEFDOC (XOR, "Boolean XOR.", "\
Returns value resulting from boolean exclusive-OR of
pair of bits in each of @var{@1@} and @var{@2@}.
")

DEFDOC (IEOR, "Boolean XOR.", "\
Returns value resulting from boolean exclusive-OR of
pair of bits in each of @var{@1@} and @var{@2@}.
")

DEFDOC (NOT, "Boolean NOT.", "\
Returns value resulting from boolean NOT of each bit
in @var{@1@}.
")

DEFDOC (ASIN, "Arc sine.", "\
Returns the arc-sine (inverse sine) of @var{@1@}
in radians.

@xref{Sin Intrinsic}, for the inverse of this function.
")

DEFDOC (DASIN, "Arc sine (archaic).", ARCHAIC (ASIN, ASin))

DEFDOC (ATAN, "Arc tangent.", "\
Returns the arc-tangent (inverse tangent) of @var{@1@}
in radians.

@xref{Tan Intrinsic}, for the inverse of this function.
")

DEFDOC (DATAN, "Arc tangent (archaic).", ARCHAIC (ATAN, ATan))

DEFDOC (ATAN2, "Arc tangent.", "\
Returns the arc-tangent (inverse tangent) of the complex
number (@var{@1@}, @var{@2@}) in radians.

@xref{Tan Intrinsic}, for the inverse of this function.
")

DEFDOC (DATAN2, "Arc tangent (archaic).", ARCHAIC_2 (ATAN2, ATan2))

DEFDOC (BIT_SIZE, "Number of bits in argument's type.", "\
Returns the number of bits (integer precision plus sign bit)
represented by the type for @var{@1@}.

@xref{BTest Intrinsic}, for how to test the value of a
bit in a variable or array.

@xref{IBSet Intrinsic}, for how to set a bit in a variable to 1.