diff options
Diffstat (limited to 'gcc/fortran/intrinsic.texi')
| -rw-r--r-- | gcc/fortran/intrinsic.texi | 740 |
1 files changed, 628 insertions, 112 deletions
diff --git a/gcc/fortran/intrinsic.texi b/gcc/fortran/intrinsic.texi index 8c160e5..3103da3 100644 --- a/gcc/fortran/intrinsic.texi +++ b/gcc/fortran/intrinsic.texi @@ -24,15 +24,22 @@ Some basic guidelines for editing this document: @tex \gdef\acosd{\mathop{\rm acosd}\nolimits} -\gdef\asind{\mathop{\rm asind}\nolimits} -\gdef\atand{\mathop{\rm atand}\nolimits} -\gdef\acos{\mathop{\rm acos}\nolimits} -\gdef\asin{\mathop{\rm asin}\nolimits} -\gdef\atan{\mathop{\rm atan}\nolimits} \gdef\acosh{\mathop{\rm acosh}\nolimits} +\gdef\acospi{\mathop{\rm acospi}\nolimits} +\gdef\acos{\mathop{\rm acos}\nolimits} +\gdef\asind{\mathop{\rm asind}\nolimits} \gdef\asinh{\mathop{\rm asinh}\nolimits} +\gdef\asinpi{\mathop{\rm asinpi}\nolimits} +\gdef\asin{\mathop{\rm asin}\nolimits} +\gdef\atan2pi{\mathop{\rm atan2pi}\nolimits} +\gdef\atand{\mathop{\rm atand}\nolimits} \gdef\atanh{\mathop{\rm atanh}\nolimits} +\gdef\atanpi{\mathop{\rm atanpi}\nolimits} +\gdef\atan{\mathop{\rm atan}\nolimits} \gdef\cosd{\mathop{\rm cosd}\nolimits} +\gdef\cospi{\mathop{\rm cospi}\nolimits} +\gdef\sinpi{\mathop{\rm sinpi}\nolimits} +\gdef\tanpi{\mathop{\rm tanpi}\nolimits} @end tex @@ -49,6 +56,7 @@ Some basic guidelines for editing this document: * @code{ACOS}: ACOS, Arccosine function * @code{ACOSD}: ACOSD, Arccosine function, degrees * @code{ACOSH}: ACOSH, Inverse hyperbolic cosine function +* @code{ACOSPI}: ACOSPI, Circular arc cosine function * @code{ADJUSTL}: ADJUSTL, Left adjust a string * @code{ADJUSTR}: ADJUSTR, Right adjust a string * @code{AIMAG}: AIMAG, Imaginary part of complex number @@ -62,12 +70,15 @@ Some basic guidelines for editing this document: * @code{ASIN}: ASIN, Arcsine function * @code{ASIND}: ASIND, Arcsine function, degrees * @code{ASINH}: ASINH, Inverse hyperbolic sine function +* @code{ASINPI}: ASINPI, Circular arc sine function * @code{ASSOCIATED}: ASSOCIATED, Status of a pointer or pointer/target pair * @code{ATAN}: ATAN, Arctangent function -* @code{ATAND}: ATAND, Arctangent function, degrees * @code{ATAN2}: ATAN2, Arctangent function * @code{ATAN2D}: ATAN2D, Arctangent function, degrees +* @code{ATAN2PI}: ATAN2PI, Circular arc tangent function +* @code{ATAND}: ATAND, Arctangent function, degrees * @code{ATANH}: ATANH, Inverse hyperbolic tangent function +* @code{ATANPI}: ATANPI, Circular arc tangent function * @code{ATOMIC_ADD}: ATOMIC_ADD, Atomic ADD operation * @code{ATOMIC_AND}: ATOMIC_AND, Atomic bitwise AND operation * @code{ATOMIC_CAS}: ATOMIC_CAS, Atomic compare and swap @@ -116,6 +127,7 @@ Some basic guidelines for editing this document: * @code{COS}: COS, Cosine function * @code{COSD}: COSD, Cosine function, degrees * @code{COSH}: COSH, Hyperbolic cosine function +* @code{COSPI}: COSPI, Circular cosine function * @code{COTAN}: COTAN, Cotangent function * @code{COTAND}: COTAND, Cotangent function, degrees * @code{COUNT}: COUNT, Count occurrences of TRUE in an array @@ -170,6 +182,7 @@ Some basic guidelines for editing this document: * @code{GETGID}: GETGID, Group ID function * @code{GETLOG}: GETLOG, Get login name * @code{GETPID}: GETPID, Process ID function +* @code{GET_TEAM}: GET_TEAM, Get the handle of a team * @code{GETUID}: GETUID, User ID function * @code{GMTIME}: GMTIME, Convert time to GMT info * @code{HOSTNM}: HOSTNM, Get system host name @@ -295,6 +308,7 @@ Some basic guidelines for editing this document: * @code{SIN}: SIN, Sine function * @code{SIND}: SIND, Sine function, degrees * @code{SINH}: SINH, Hyperbolic sine function +* @code{SINPI}: SINPI, Circular sine function * @code{SIZE}: SIZE, Function to determine the size of an array * @code{SIZEOF}: SIZEOF, Determine the size in bytes of an expression * @code{SLEEP}: SLEEP, Sleep for the specified number of seconds @@ -311,6 +325,8 @@ Some basic guidelines for editing this document: * @code{TAN}: TAN, Tangent function * @code{TAND}: TAND, Tangent function, degrees * @code{TANH}: TANH, Hyperbolic tangent function +* @code{TANPI}: TANPI, Circular tangent function +* @code{TEAM_NUMBER}: TEAM_NUMBER, Retrieve team id of given team * @code{THIS_IMAGE}: THIS_IMAGE, Cosubscript index of this image * @code{TIME}: TIME, Time function * @code{TIME8}: TIME8, Time function (64-bit) @@ -752,6 +768,62 @@ Inverse function: @* +@node ACOSPI +@section @code{ACOSPI} --- Circular arc cosine function +@fnindex ACOSPI +@cindex trigonometric function, cosine, inverse + +@table @asis +@item @emph{Description}: +@code{ACOSPI(X)} computes @math{ \acos(x) / \pi}, which is a measure +of an angle in half-revolutions. + +@item @emph{Standard}: +Fortran 2023 + +@item @emph{Class}: +Elemental function + +@item @emph{Syntax}: +@code{RESULT = ACOSPI(X)} + +@item @emph{Arguments}: +@multitable @columnfractions .15 .70 +@item @var{X} @tab The type shall be @code{REAL} with @math{-1 \leq x \leq 1}. +@end multitable + +@item @emph{Return value}: +The return value has the same type and kind as @var{X}. +It is expressed in half-revolutions and satisfies +@math{ 0 \leq \acospi (x) \leq 1}. + +@item @emph{Example}: +@smallexample +program test_acospi + implicit none + real, parameter :: x = 0.123, y(3) = [0.123, 0.45, 0.8] + real, parameter :: a = acospi(x), b(3) = acospi(y) + call foo(x, y) +contains + subroutine foo(u, v) + real, intent(in) :: u, v(:) + real :: f, g(size(v)) + f = acospi(u) + g = acospi(v) + if (abs(a - f) > 8 * epsilon(f)) stop 1 + if (any(abs(g - b) > 8 * epsilon(f))) stop 2 + end subroutine foo +end program test_acospi +@end smallexample + +@item @emph{See also}: +@ref{ASINPI} @* +@ref{ATAN2PI} @* +@ref{ATANPI} @* +@end table + + + @node ADJUSTL @section @code{ADJUSTL} --- Left adjust a string @fnindex ADJUSTL @@ -1467,6 +1539,62 @@ Inverse function: @* +@node ASINPI +@section @code{ASINPI} --- Circular arc sine function +@fnindex ASINPI +@cindex trigonometric function, sine, inverse + +@table @asis +@item @emph{Description}: +@code{ASINPI(X)} computes @math{ \asin(x) / \pi}, which is a measure +of an angle in half-revolutions. + +@item @emph{Standard}: +Fortran 2023 + +@item @emph{Class}: +Elemental function + +@item @emph{Syntax}: +@code{RESULT = ASINPI(X)} + +@item @emph{Arguments}: +@multitable @columnfractions .15 .70 +@item @var{X} @tab The type shall be @code{REAL} with @math{-1 \leq x \leq 1}. +@end multitable + +@item @emph{Return value}: +The return value has the same type and kind as @var{X}. +It is expressed in half-revolutions and satisfies +@math{ -0.5 \leq \asinpi (x) \leq 0.5}. + +@item @emph{Example}: +@smallexample +program test_asinpi + implicit none + real, parameter :: x = 0.123, y(3) = [0.123, 0.45, 0.8] + real, parameter :: a = asinpi(x), b(3) = asinpi(y) + call foo(x, y) +contains + subroutine foo(u, v) + real, intent(in) :: u, v(:) + real :: f, g(size(v)) + f = asinpi(u) + g = asinpi(v) + if (abs(a - f) > 8 * epsilon(f)) stop 1 + if (any(abs(g - b) > 8 * epsilon(f))) stop 2 + end subroutine foo +end program test_asinpi +@end smallexample + +@item @emph{See also}: +@ref{ACOSPI} @* +@ref{ATAN2PI} @* +@ref{ATANPI} @* +@end table + + + @node ASSOCIATED @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair @fnindex ASSOCIATED @@ -1545,7 +1673,7 @@ Fortran 90 and later @node ATAN -@section @code{ATAN} --- Arctangent function +@section @code{ATAN} --- Arctangent function @fnindex ATAN @fnindex DATAN @cindex trigonometric function, tangent, inverse @@ -1606,65 +1734,6 @@ Degrees function: @* -@node ATAND -@section @code{ATAND} --- Arctangent function, degrees -@fnindex ATAND -@fnindex DATAND -@cindex trigonometric function, tangent, inverse, degrees -@cindex tangent, inverse, degrees - -@table @asis -@item @emph{Synopsis}: -@multitable @columnfractions .80 -@item @code{RESULT = ATAND(X)} -@end multitable - -@item @emph{Description}: -@code{ATAND(X)} computes the arctangent of @var{X} in degrees (inverse of -@ref{TAND}). - -@item @emph{Class}: -Elemental function - -@item @emph{Arguments}: -@multitable @columnfractions .15 .70 -@item @var{X} @tab The type shall be @code{REAL}; -if @var{Y} is present, @var{X} shall be REAL. -@item @var{Y} @tab The type and kind type parameter shall be the same as @var{X}. -@end multitable - -@item @emph{Return value}: -The return value is of the same type and kind as @var{X}. -The result is in degrees and lies in the range -@math{-90 \leq \Re \atand(x) \leq 90}. - -@item @emph{Example}: -@smallexample -program test_atand - real(8) :: x = 2.866_8 - x = atand(x) -end program test_atand -@end smallexample - -@item @emph{Specific names}: -@multitable @columnfractions .23 .23 .20 .30 -@headitem Name @tab Argument @tab Return type @tab Standard -@item @code{ATAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 2023 -@item @code{DATAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension -@end multitable - -@item @emph{Standard}: -Fortran 2023 - -@item @emph{See also}: -Inverse function: @* -@ref{TAND} @* -Radians function: @* -@ref{ATAN} -@end table - - - @node ATAN2 @section @code{ATAN2} --- Arctangent function @fnindex ATAN2 @@ -1793,6 +1862,117 @@ Radians function: @* @ref{ATAN2} @end table + + +@node ATAN2PI +@section @code{ATAN2PI} --- Circular arc tangent function +@fnindex ATAN2PI +@cindex trigonometric function, tangent, inverse + +@table @asis +@item @emph{Description}: +@code{ATAN2PI(Y, X)} computes @math{ {\rm {atan2}}(y, x) / \pi}, +and provides a measure of an angle in half-revolutions within +the proper quadrant. + +@item @emph{Standard}: +Fortran 2023 + +@item @emph{Class}: +Elemental function + +@item @emph{Syntax}: +@code{RESULT = ATAN2PI(Y, X)} + +@item @emph{Arguments}: +@multitable @columnfractions .15 .70 +@item @var{Y} @tab The type shall be @code{REAL}. +@item @var{X} @tab The type and kind type parameter shall be the +same as @var{Y}. If @var{Y} is zero, then @var{X} shall be nonzero. +@end multitable + +@item @emph{Return value}: +The return value has the same type and kind type parameter as @var{Y} +and satisfies @math{-1 \leq {\rm {atan2}}(y, x) / \pi \leq 1}. + +@item @emph{Example}: +@smallexample +program test_atan2pi + real(kind=4) :: x = 1.e0_4, y = 0.5e0_4 + x = atan2pi(y, x) +end program test_atan2pi +@end smallexample + +@item @emph{See also}: +@ref{ACOSPI} @* +@ref{ASINPI} @* +@ref{ATANPI} @* +@end table + + + +@node ATAND +@section @code{ATAND} --- Arctangent function, degrees +@fnindex ATAND +@fnindex DATAND +@cindex trigonometric function, tangent, inverse, degrees +@cindex tangent, inverse, degrees + +@table @asis +@item @emph{Synopsis}: +@multitable @columnfractions .80 +@item @code{RESULT = ATAND(X)} +@item @code{RESULT = ATAND(Y, X)} +@end multitable + +@item @emph{Description}: +@code{ATAND(X)} computes the arctangent of @var{X} in degrees (inverse of +@ref{TAND}). + +@item @emph{Class}: +Elemental function + +@item @emph{Arguments}: +@multitable @columnfractions .15 .70 +@item @var{X} @tab The type shall be @code{REAL}. +@item @var{Y} @tab The type and kind type parameter shall be the same as @var{X}. +@end multitable + +@item @emph{Return value}: +The return value is of the same type and kind as @var{X}. +If @var{Y} is present, the result is identical to @code{ATAN2D(Y, X)}. +Otherwise, the result is in degrees and lies in the range +@math{-90 \leq \atand(x) \leq 90}. + +@item @emph{Example}: +@smallexample +program test_atand + real(8) :: x = 2.866_8 + real(4) :: x1 = 1.e0_4, y1 = 0.5e0_4 + x = atand(x) + x1 = atand(y1, x1) +end program test_atand +@end smallexample + +@item @emph{Specific names}: +@multitable @columnfractions .23 .23 .20 .30 +@headitem Name @tab Argument @tab Return type @tab Standard +@item @code{ATAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 2023 +@item @code{DATAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension +@end multitable + +@item @emph{Standard}: +Fortran 2023 + +@item @emph{See also}: +Inverse function: @* +@ref{TAND} @* +Radians function: @* +@ref{ATAN} +@end table + + + @node ATANH @section @code{ATANH} --- Inverse hyperbolic tangent function @fnindex ATANH @@ -1846,6 +2026,70 @@ Inverse function: @* +@node ATANPI +@section @code{ATANPI} --- Circular arc tangent function +@fnindex ATANPI +@cindex trigonometric function, tangent, inverse + +@table @asis +@item @emph{Description}: +@code{ATANPI(X)} computes @math{ \atan(x) / \pi}. +@code{ATANPI(Y, X)} computes @math{ {\rm atan2}(y, x) / \pi}. +These provide a measure of an angle in half-revolutions. + +@item @emph{Standard}: +Fortran 2023 + +@item @emph{Class}: +Elemental function + +@item @emph{Syntax}: +@multitable @columnfractions .80 +@item @code{RESULT = ATANPI(X)} +@item @code{RESULT = ATANPI(Y, X)} +@end multitable + +@item @emph{Arguments}: +@multitable @columnfractions .15 .70 +@item @var{Y} @tab The type shall be @code{REAL}. +@item @var{X} @tab If @var{Y} appears, @var{X} shall have the same type +and kind as @var{Y}. If @var{Y} is zero, then @var{X} shall not be zero. +If @var{Y} does not appear in a function reference, then @var{X} shall be +@code{REAL}. +@end multitable + +@item @emph{Return value}: +The return value has the same type and kind as @var{X}. +It is expressed in half-revolutions and satisfies +@math{ -0.5 \leq \atanpi (x) \leq 0.5}. + +@item @emph{Example}: +@smallexample +program test_atanpi + implicit none + real, parameter :: x = 0.123, y(3) = [0.123, 0.45, 0.8] + real, parameter :: a = atanpi(x), b(3) = atanpi(y) + call foo(x, y) +contains + subroutine foo(u, v) + real, intent(in) :: u, v(:) + real :: f, g(size(v)) + f = atanpi(u) + g = atanpi(v) + if (abs(a - f) > 8 * epsilon(f)) stop 1 + if (any(abs(g - b) > 8 * epsilon(f))) stop 2 + end subroutine foo +end program test_atanpi +@end smallexample + +@item @emph{See also}: +@ref{ACOSPI} @* +@ref{ASINPI} @* +@ref{ATAN2PI} @* +@end table + + + @node ATOMIC_ADD @section @code{ATOMIC_ADD} --- Atomic ADD operation @fnindex ATOMIC_ADD @@ -4386,6 +4630,57 @@ Inverse function: @* +@node COSPI +@section @code{COSPI} --- Circular cosine function +@fnindex COSPI +@cindex trigonometric function, cosine +@cindex cosine + +@table @asis +@item @emph{Description}: +@code{COSPI(X)} computes @math{\cos(\pi x)} without performing +an explicit multiplication by @math{\pi}. This is achieved +through argument reduction where @math{ x = n + r } with +@math{n} an integer and @math{0 \leq r \le 1}. +Due to the +properties of floating-point arithmetic, the useful range +for @var{X} is defined by +@code{ABS(X) <= REAL(2,KIND(X))**DIGITS(X)}. + +@item @emph{Standard}: +Fortran 2023 + +@item @emph{Class}: +Elemental function + +@item @emph{Syntax}: +@code{RESULT = COSPI(X)} + +@item @emph{Arguments}: +@multitable @columnfractions .15 .70 +@item @var{X} @tab The type shall be @code{REAL}. +@end multitable + +@item @emph{Return value}: +The return value is of the same type and kind as @var{X}. +The result is in half-revolutions and satisfies +@math{ -1 \leq \cospi (x) \leq 1}. + +@item @emph{Example}: +@smallexample +program test_cospi + real :: x = 0.0 + x = cospi(x) +end program test_cospi +@end smallexample + +@item @emph{See also}: +@ref{ACOSPI} @* +@ref{COS} @* +@end table + + + @node COTAN @section @code{COTAN} --- Cotangent function @fnindex COTAN @@ -6706,9 +7001,11 @@ Subroutine, function @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}. -@item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}. -@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0 -on success and a system specific error code otherwise. +@item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(13)} +of the default kind. +@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER} +of the default kind. +Returns 0 on success and a system specific error code otherwise. @end multitable @item @emph{Example}: @@ -7336,6 +7633,59 @@ GNU extension +@node GET_TEAM +@section @code{GET_TEAM} --- Get the handle of a team +@fnindex GET_TEAM +@cindex coarray, @code{GET_TEAM} +@cindex images, get a handle to a team + +@table @asis +@item @emph{Synopsis}: +@code{RESULT = GET_TEAM([LEVEL])} + +@item @emph{Description}: +Returns the handle of the current team, if @var{LEVEL} is not given. Or the +team specified by @var{LEVEL}, where @var{LEVEL} is one of the constants +@code{INITIAL_TEAM}, @code{PARENT_TEAM} or @code{CURRENT_TEAM} from the +intrinsic module @code{ISO_FORTRAN_ENV}. Calling the function with +@code{PARENT_TEAM} while being on the initial team, returns a handle to the +initial team. This ensures that always a valid team is returned, given that +team handles can neither be checked for validity nor compared with each other +or null. + +@item @emph{Class}: +Transformational function + +@item @emph{Return value}: +An opaque handle of @code{TEAM_TYPE} from the intrinsic module +@code{ISO_FORTRAN_ENV}. + +@item @emph{Example}: +@smallexample +program info + use, intrinsic :: iso_fortran_env + type(team_type) :: init, curr, par, nt + + init = get_team() + curr = get_team(current_team) ! init equals curr here + form team(1, nt) + change team(nt) + curr = get_team() ! or get_team(current_team) + par = get_team(parent_team) ! par equals init here + end team +end program info +@end smallexample + +@item @emph{Standard}: +Fortran 2018 or later + +@item @emph{See also}: +@ref{THIS_IMAGE}, @* +@ref{ISO_FORTRAN_ENV} +@end table + + + @node GETUID @section @code{GETUID} --- User ID function @fnindex GETUID @@ -9958,8 +10308,10 @@ Subroutine, function @multitable @columnfractions .15 .70 @item @var{NAME} @tab The type shall be @code{CHARACTER} of the default kind, a valid path within the file system. -@item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}. -@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. +@item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(13)} +of the default kind. +@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER} +of the default kind. Returns 0 on success and a system specific error code otherwise. @end multitable @@ -11372,47 +11724,48 @@ Fortran 95 and later @table @asis @item @emph{Synopsis}: -@code{RESULT = NUM_IMAGES(DISTANCE, FAILED)} +@multitable @columnfractions .80 +@item @code{RESULT = NUM_IMAGES([TEAM])} +@item @code{RESULT = NUM_IMAGES(TEAM_NUMBER)} +@end multitable @item @emph{Description}: -Returns the number of images. +Returns the number of images in the current team or the given team. @item @emph{Class}: Transformational function @item @emph{Arguments}: @multitable @columnfractions .15 .70 -@item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer -@item @var{FAILED} @tab (optional, intent(in)) Scalar logical expression +@item @var{TEAM} @tab (optional, intent(in)) If present, return the number of +images in the given team; if absent, return the number of images in the +current team. +@item @var{TEAM_NUMBER} @tab (intent(in)) The number as given in the +@code{FORM TEAM} statement. @end multitable @item @emph{Return value}: -Scalar default-kind integer. If @var{DISTANCE} is not present or has value 0, -the number of images in the current team is returned. For values smaller or -equal distance to the initial team, it returns the number of images index -on the ancestor team that has a distance of @var{DISTANCE} from the invoking -team. If @var{DISTANCE} is larger than the distance to the initial team, the -number of images of the initial team is returned. If @var{FAILED} is not present -the total number of images is returned; if it has the value @code{.TRUE.}, -the number of failed images is returned, otherwise, the number of images that -do have not the failed status. +Scalar default-kind integer. Can be called without any arguments or a team +type argument or a team_number argument. @item @emph{Example}: @smallexample +use, intrinsic :: iso_fortran_env INTEGER :: value[*] INTEGER :: i -value = THIS_IMAGE() -SYNC ALL -IF (THIS_IMAGE() == 1) THEN - DO i = 1, NUM_IMAGES() - WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i] - END DO -END IF +type(team_type) :: t + +! When running with 4 images +print *, num_images() ! 4 + +form team (mod(this_image(), 2), t) +print *, num_images(t) ! 2 +print *, num_images(-1) ! 4 @end smallexample @item @emph{Standard}: -Fortran 2008 and later. With @var{DISTANCE} or @var{FAILED} argument, -Technical Specification (TS) 18508 or later +Fortran 2008 and later. With @var{TEAM} or @var{TEAM_NUMBER} argument, +Fortran 2018 and later. @item @emph{See also}: @ref{THIS_IMAGE}, @* @@ -13618,6 +13971,57 @@ a GNU extension +@node SINPI +@section @code{SINPI} --- Circular sine function +@fnindex SINPI +@cindex trigonometric function, sine +@cindex sine + +@table @asis +@item @emph{Description}: +@code{SINPI(X)} computes @math{\sin(\pi x)} without performing +an explicit multiplication by @math{\pi}. This is achieved +through argument reduction where @math{ |x| = n + r } with +@math{n} an integer and @math{0 \leq r \le 1}. +Due to the +properties of floating-point arithmetic, the useful range +for @var{X} is defined by +@code{ABS(X) <= REAL(2,KIND(X))**DIGITS(X)}. + +@item @emph{Standard}: +Fortran 2023 + +@item @emph{Class}: +Elemental function + +@item @emph{Syntax}: +@code{RESULT = SINPI(X)} + +@item @emph{Arguments}: +@multitable @columnfractions .15 .70 +@item @var{X} @tab The type shall be @code{REAL}. +@end multitable + +@item @emph{Return value}: +The return value is of the same type and kind as @var{X}. +The result is in half-revolutions and satisfies +@math{ -1 \leq \sinpi (x) \leq 1}. + +@item @emph{Example}: +@smallexample +program test_sinpi + real :: x = 0.0 + x = sinpi(x) +end program test_sinpi +@end smallexample + +@item @emph{See also}: +@ref{ASINPI} @* +@ref{SIN} @* +@end table + + + @node SIZE @section @code{SIZE} --- Determine the size of an array @fnindex SIZE @@ -13991,6 +14395,8 @@ The elements that are obtained and stored in the array @code{VALUES}: Not all these elements are relevant on all systems. If an element is not relevant, it is returned as 0. +If the value of an element would overflow the range of default integer, +a -1 is returned instead. This intrinsic is provided in both subroutine and function forms; however, only one form can be used in any given program unit. @@ -14002,9 +14408,11 @@ Subroutine, function @multitable @columnfractions .15 .70 @item @var{NAME} @tab The type shall be @code{CHARACTER}, of the default kind and a valid path within the file system. -@item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}. -@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0 -on success and a system specific error code otherwise. +@item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(13)} +of the default kind. +@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER} +of the default kind. +Returns 0 on success and a system specific error code otherwise. @end multitable @item @emph{Example}: @@ -14467,6 +14875,103 @@ Fortran 77 and later, for a complex argument Fortran 2008 or later +@node TEAM_NUMBER +@section @code{TEAM_NUMBER} --- Retrieve team id of given team +@fnindex TEAM_NUMBER +@cindex coarray, @code{TEAM_NUMBER} +@cindex teams, index of given team + +@table @asis +@item @emph{Synopsis}: +@item @code{RESULT = TEAM_NUMBER([TEAM])} + +@item @emph{Description}: +Returns the team id for the given @var{TEAM} as assigned by @code{FORM TEAM}. +If @var{TEAM} is absent, returns the team number of the current team. + +@item @emph{Class}: +Transformational function + +@item @emph{Arguments}: +@multitable @columnfractions .15 .70 +@item @var{TEAM} @tab (optional, intent(in)) The handle of the team for which +the number, aka id, is desired. +@end multitable + +@item @emph{Return value}: +Default integer. The id as given in a call @code{FORM TEAM}. Applying +@code{TEAM_NUMBER} to the initial team will result in @code{-1} to be returned. +Returns the id of the current team, if @var{TEAM} is null. + +@item @emph{Example}: +@smallexample +use, intrinsic :: iso_fortran_env +type(team_type) :: t + +print *, team_number() ! -1 +form team (99, t) +print *, team_number(t) ! 99 +@end smallexample + +@item @emph{Standard}: +Fortran 2018 and later. + +@item @emph{See also}: +@ref{GET_TEAM}, @* +@ref{TEAM_NUMBER} +@end table + + + +@node TANPI +@section @code{TANPI} --- Circular tangent function +@fnindex TANPI +@cindex trigonometric function, tangent +@cindex tangent + +@table @asis +@item @emph{Description}: +@code{TANPI(X)} computes @math{\tan(\pi x)} without performing +an explicit multiplication by @math{\pi}. This is achieved +through argument reduction where @math{ |x| = n + r } with +@math{n} an integer and @math{0 \leq r \le 1}. +Due to the +properties of floating-point arithmetic, the useful range +for @var{X} is defined by +@code{ABS(X) <= REAL(2,KIND(X))**DIGITS(X)}. + +@item @emph{Standard}: +Fortran 2023 + +@item @emph{Class}: +Elemental function + +@item @emph{Syntax}: +@code{RESULT = TANPI(X)} + +@item @emph{Arguments}: +@multitable @columnfractions .15 .70 +@item @var{X} @tab The type shall be @code{REAL}. +@end multitable + +@item @emph{Return value}: +The return value is of the same type and kind as @var{X}. + +@item @emph{Example}: +@smallexample +program test_tanpi + real :: x = 0.0 + x = tanpi(x) +end program test_tanpi +@end smallexample + +@item @emph{See also}: +@ref{ATANPI} @* +@ref{TAN} @* +@end table + + + @node THIS_IMAGE @section @code{THIS_IMAGE} --- Function that returns the cosubscript index of this image @fnindex THIS_IMAGE @@ -14476,9 +14981,8 @@ Fortran 77 and later, for a complex argument Fortran 2008 or later @table @asis @item @emph{Synopsis}: @multitable @columnfractions .80 -@item @code{RESULT = THIS_IMAGE()} -@item @code{RESULT = THIS_IMAGE(DISTANCE)} -@item @code{RESULT = THIS_IMAGE(COARRAY [, DIM])} +@item @code{RESULT = THIS_IMAGE([TEAM])} +@item @code{RESULT = THIS_IMAGE(COARRAY [, DIM][, TEAM])} @end multitable @item @emph{Description}: @@ -14489,8 +14993,8 @@ Transformational function @item @emph{Arguments}: @multitable @columnfractions .15 .70 -@item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer -(not permitted together with @var{COARRAY}). +@item @var{TEAM} @tab (optional, intent(in)) The team for which the index of +this image is desired. The current team is used, when no team is given. @item @var{COARRAY} @tab Coarray of any type (optional; if @var{DIM} present, required). @item @var{DIM} @tab default integer scalar (optional). If present, @@ -14499,16 +15003,16 @@ present, required). @item @emph{Return value}: Default integer. If @var{COARRAY} is not present, it is scalar; if -@var{DISTANCE} is not present or has value 0, its value is the image index on -the invoking image for the current team, for values smaller or equal -distance to the initial team, it returns the image index on the ancestor team -that has a distance of @var{DISTANCE} from the invoking team. If -@var{DISTANCE} is larger than the distance to the initial team, the image -index of the initial team is returned. Otherwise when the @var{COARRAY} is +@var{TEAM} is not present, its value is the image index on the invoking image +for the current team; if @var{TEAM} is present, returns the image index of +the invoking image as given to the @code{FORM TEAM (..., NEW_INDEX=..)} call, +or a implementation specific unique number, when @code{NEW_INDEX=} was absent +from @code{FORM TEAM}. Otherwise when the @var{COARRAY} is present, if @var{DIM} is not present, a rank-1 array with corank elements is returned, containing the cosubscripts for @var{COARRAY} specifying the invoking -image. If @var{DIM} is present, a scalar is returned, with the value of -the @var{DIM} element of @code{THIS_IMAGE(COARRAY)}. +image (in the team when @var{TEAM} is present). If @var{DIM} is present, a +scalar is returned, with the value of the @var{DIM} element of +@code{THIS_IMAGE(COARRAY)}. @item @emph{Example}: @smallexample @@ -14523,13 +15027,12 @@ IF (THIS_IMAGE() == 1) THEN END IF ! Check whether the current image is the initial image -IF (THIS_IMAGE(HUGE(1)) /= THIS_IMAGE()) +IF (THIS_IMAGE(GET_TEAM(INITIAL_TEAM)) /= THIS_IMAGE()) error stop "something is rotten here" @end smallexample @item @emph{Standard}: -Fortran 2008 and later. With @var{DISTANCE} argument, -Technical Specification (TS) 18508 or later +Fortran 2008 and later. With @var{TEAM} argument, Fortran 2018 or later @item @emph{See also}: @ref{NUM_IMAGES}, @* @@ -15354,12 +15857,18 @@ parameters of the @code{CHARACTER} type. (Fortran 2008 or later.) @item @code{CHARACTER_STORAGE_SIZE}: Size in bits of the character storage unit. +@item @code{CURRENT_TEAM}: +The argument to @ref{GET_TEAM} to retrieve a handle of the current team. + @item @code{ERROR_UNIT}: Identifies the preconnected unit used for error reporting. @item @code{FILE_STORAGE_SIZE}: Size in bits of the file-storage unit. +@item @code{INTIAL_TEAM}: +Argument to @ref{GET_TEAM} to retrieve a handle of the initial team. + @item @code{INPUT_UNIT}: Identifies the preconnected unit identified by the asterisk (@code{*}) in @code{READ} statement. @@ -15397,6 +15906,9 @@ parameters of the @code{LOGICAL} type. (Fortran 2008 or later.) Identifies the preconnected unit identified by the asterisk (@code{*}) in @code{WRITE} statement. +@item @code{PARENT_TEAM}: +Argument to @ref{GET_TEAM} to retrieve a handle to the parent team. + @item @code{REAL32}, @code{REAL64}, @code{REAL128}: Kind type parameters to specify a REAL type with a storage size of 32, 64, and 128 bits. It is negative if a target platform @@ -15445,6 +15957,10 @@ Derived type with private components to be use with the @code{LOCK} and @code{UNLOCK} statement. A variable of its type has to be always declared as coarray and may not appear in a variable-definition context. (Fortran 2008 or later.) +@item @code{TEAM_TYPE}: +An opaque type for handling teams. Note that a variable of type +@code{TEAM_TYPE} is not comparable with other variables of the same or other +types nor with null. @end table The module also provides the following intrinsic procedures: |