Manual Reference Pages - mvbits (3fortran)

NAME

MVBITS(3) - [BIT:COPY] Reproduce bit patterns found in one integer in another

SYNOPSIS

call mvbits(from, frompos, len, to, topos)

        elemental subroutine mvbits( from, frompos, len, to, topos )

         integer(kind=KIND),intent(in)    :: from
         integer(kind=**),intent(in)      :: frompos
         integer(kind=**),intent(in)      :: len
         integer(kind=KIND),intent(inout) :: to
         integer(kind=**),intent(in)      :: topos

CHARACTERISTICS

o FROM is an integer

o FROMPOS is an integer

o LEN is an integer

o TO is an integer of the same kind as FROM.

o TOPOS is an integer

DESCRIPTION

MVBITS(3) copies a bit pattern found in a range of adjacent bits in the integer FROM to a specified position in another integer TO (which is of the same kind as FROM). It otherwise leaves the bits in TO as-is.
The bit positions copied must exist within the value of FROM. That is, the values of FROMPOS+LEN-1 and TOPOS+LEN-1 must be nonnegative and less than BIT_SIZE(from).
The bits are numbered 0 to BIT_SIZE(I)-1, from right to left.

OPTIONS

o FROM : An integer to read bits from.

o FROMPOS : FROMPOS is the position of the first bit to copy. It is a nonnegative integer value < BIT_SIZE(FROM).

o LEN : A nonnegative integer value that indicates how many bits to copy from FROM. It must not specify copying bits past the end of FROM. That is, FROMPOS + LEN must be less than or equal to BIT_SIZE(FROM).

o TO : The integer variable to place the copied bits into. It must be of the same kind as FROM and may even be the same variable as FROM, or associated to it.
TO is set by copying the sequence of bits of length LEN, starting at position FROMPOS of FROM to position TOPOS of TO. No other bits of TO are altered. On return, the LEN bits of TO starting at TOPOS are equal to the value that the LEN bits of FROM starting at FROMPOS had on entry.

o TOPOS : A nonnegative integer value indicating the starting location in TO to place the specified copy of bits from FROM. TOPOS + LEN must be less than or equal to BIT_SIZE(TO).

EXAMPLES

Sample program that populates a new 32-bit integer with its bytes in reverse order from the input value (ie. changes the Endian of the integer).

    program demo_mvbits
    use,intrinsic :: iso_fortran_env,  only : int8, int16, int32, int64
    implicit none
    integer(kind=int32) :: intfrom, intto, abcd_int
    character(len=*),parameter :: bits= ’(g0,t30,b32.32)’
    character(len=*),parameter :: fmt= ’(g0,t30,a,t40,b32.32)’

        intfrom=huge(0)  ! all bits are 1 accept the sign bit
        intto=0          ! all bits are 0

        !! CHANGE BIT 0
        ! show the value and bit pattern
        write(*,bits)intfrom,intfrom
        write(*,bits)intto,intto

        ! copy bit 0 from intfrom to intto to show the rightmost bit changes
        !          (from,    frompos, len,    to, topos)
        call mvbits(intfrom,       0,   1, intto,     0) ! change bit 0
        write(*,bits)intto,intto

        !! COPY PART OF A VALUE TO ITSELF
        ! can copy bit from a value to itself
        call mvbits(intfrom,0,1,intfrom,31)
        write(*,bits)intfrom,intfrom

        !! MOVING BYTES AT A TIME
        ! make native integer value with bit patterns
        ! that happen to be the same as the beginning of the alphabet
        ! to make it easy to see the bytes are reversed
        abcd_int=transfer(’abcd’,0)
        ! show the value and bit pattern
        write(*,*)’native’
        write(*,fmt)abcd_int,abcd_int,abcd_int

        ! change endian of the value
        abcd_int=int_swap32(abcd_int)
        ! show the values and their bit pattern
        write(*,*)’non-native’
        write(*,fmt)abcd_int,abcd_int,abcd_int

     contains

     pure elemental function int_swap32(intin) result(intout)
     ! Convert a 32 bit integer from big Endian to little Endian,
     ! or conversely from little Endian to big Endian.
     !
     integer(kind=int32), intent(in)  :: intin
     integer(kind=int32) :: intout
        ! copy bytes from input value to new position in output value
        !          (from,  frompos, len,     to, topos)
        call mvbits(intin,       0,   8, intout,    24) ! byte1 to byte4
        call mvbits(intin,       8,   8, intout,    16) ! byte2 to byte3
        call mvbits(intin,      16,   8, intout,     8) ! byte3 to byte2
        call mvbits(intin,      24,   8, intout,     0) ! byte4 to byte1
     end function int_swap32

     end program demo_mvbits

Results:

> 2147483647 01111111111111111111111111111111 > 0 00000000000000000000000000000000 > 1 00000000000000000000000000000001 > -1 11111111111111111111111111111111 > native > 1684234849 abcd 01100100011000110110001001100001 > non-native > 1633837924 dcba 01100001011000100110001101100100

STANDARD

Fortran 95

o	FROM is an integer
o	FROMPOS is an integer
o	LEN is an integer
o	TO is an integer of the same kind as FROM.
o	TOPOS is an integer

o	FROM : An integer to read bits from.
o	FROMPOS : FROMPOS is the position of the first bit to copy. It is a nonnegative integer value < BIT_SIZE(FROM).
o	LEN : A nonnegative integer value that indicates how many bits to copy from FROM. It must not specify copying bits past the end of FROM. That is, FROMPOS + LEN must be less than or equal to BIT_SIZE(FROM).
o	TO : The integer variable to place the copied bits into. It must be of the same kind as FROM and may even be the same variable as FROM, or associated to it. TO is set by copying the sequence of bits of length LEN, starting at position FROMPOS of FROM to position TOPOS of TO. No other bits of TO are altered. On return, the LEN bits of TO starting at TOPOS are equal to the value that the LEN bits of FROM starting at FROMPOS had on entry.
o	TOPOS : A nonnegative integer value indicating the starting location in TO to place the specified copy of bits from FROM. TOPOS + LEN must be less than or equal to BIT_SIZE(TO).