Manual Reference Pages - out_of_range (3fortran)

NAME

OUT_OF_RANGE(3) - [TYPE:CONVERSION] Whether a numeric value can be converted safely to another type

SYNOPSIS

result = out_of_range (x, mold [, round])

         elemental logical function(x, mold, round)

          type(TYPE(kind=**)),intent(in) :: x
          type(TYPE(kind=**)),intent(in) :: mold
          logical,intent(in),optional    :: round

CHARACTERISTICS

o X is of type integer or real.

o MOLD is an integer or real scalar.

o ROUND is a logical scalar.

o the result is a default logical.

DESCRIPTION

OUT_OF_RANGE(3) determines whether a value X can be converted safely to a real or integer variable the same type and kind as MOLD.
For example, if INT8 is the KIND name for an 8-bit binary integer type, then for
        logical :: L1, L2
        L1=out_of_range(-128.5, 0_int8)
        L2=out_of_range(-128.5, 0_int8,.true.)
        end
L1 likely will have the value .FALSE. because the value will be truncated to -128.0, which is a representable integer number on a two’s complement machine.
L2 will be .TRUE. because it will be rounded to -129.0, which is not likely to be a representable eight-bit integer.

OPTIONS

o X : a scalar to be tested for whether it can be stored in a variable of the type and kind of MOLD

o MOLD : the type and kind of the variable (but not the value) is used to identify the characteristics of the variable type to fit X into.

o ROUND : flag whether to round the value of X before validating it as a value like MOLD.
ROUND can only be present if X is of type real and MOLD is of type integer.

RESULT

From the standard:
Case (i): If MOLD is of type integer, and ROUND is absent or present with the value false, the result is true if and only if the value of X is an IEEE infinity or NaN, or if the integer with largest magnitude that lies between zero and X inclusive is not representable by objects with the type and kind of MOLD.
Case (ii): If MOLD is of type integer, and ROUND is present with the value true, the result is true if and only if the value of X is an IEEE infinity or NaN, or if the integer nearest X, or the integer of greater magnitude if two integers are equally near to X, is not representable by objects with the type and kind of MOLD.
Case (iii): Otherwise, the result is true if and only if the value of X is an IEEE infinity or NaN that is not supported by objects of the type and kind of MOLD, or if X is a finite number and the result of rounding the value of X (according to the IEEE rounding mode if appropriate) to the extended model for the kind of MOLD has magnitude larger than that of the largest finite number with the same sign as X that is representable by objects with the type and kind of MOLD.

NOTE

MOLD is required to be a scalar because the only information taken from it is its type and kind. Allowing an array MOLD would require that it be conformable with X. ROUND is scalar because allowing an array rounding mode would have severe performance difficulties on many processors.

EXAMPLES

Sample program:

    program demo_out_of_range
    use, intrinsic :: iso_fortran_env, only : int8, int16, int32, int64
    use, intrinsic :: iso_fortran_env, only : real32, real64, real128
    implicit none
    integer            :: i
    integer(kind=int8) :: i8, j8

        ! compilers are not required to produce an error on out of range.
        ! here storing the default integers into 1-byte integers
        ! incorrectly can have unexpected results
        do i=127,130
           i8=i
           j8=-i
           ! OUT_OF_RANGE(3) can let you check if the value will fit
           write(*,*)i8,j8,’ might have expected’,i,-i, &
            & out_of_range( i,i8), &
            & out_of_range(-i,i8)
        enddo
        write(*,*) ’RANGE IS ’,-1-huge(0_int8),’TO’,huge(0_int8)
        ! the real -128.5 is truncated to -128 and is in range
        write(*,*) out_of_range (  -128.5, 0_int8)         ! false

        ! the real -128.5 is rounded to -129 and is not in range
        write(*,*) out_of_range (  -128.5, 0_int8, .true.) ! true

    end program demo_out_of_range

Results:

> 127 -127 might have expected 127 -127 F F > -128 -128 might have expected 128 -128 T F > -127 127 might have expected 129 -129 T T > -126 126 might have expected 130 -130 T T > RANGE IS -128 TO 127 > F > T

STANDARD

FORTRAN 2018

o	AIMAG(3) - Imaginary part of complex number
o	CMPLX(3) - Convert values to a complex type
o	DBLE(3) - Double conversion function
o	INT(3) - Truncate towards zero and convert to integer
o	NINT(3) - Nearest whole number
o	REAL(3) - Convert to real type

o	X is of type integer or real.
o	MOLD is an integer or real scalar.
o	ROUND is a logical scalar.
o	the result is a default logical.

o	X : a scalar to be tested for whether it can be stored in a variable of the type and kind of MOLD
o	MOLD : the type and kind of the variable (but not the value) is used to identify the characteristics of the variable type to fit X into.
o	ROUND : flag whether to round the value of X before validating it as a value like MOLD. ROUND can only be present if X is of type real and MOLD is of type integer.