Skip to content

Latest commit

 

History

History
1531 lines (966 loc) · 39.8 KB

stdlib_bitsets.md

File metadata and controls

1531 lines (966 loc) · 39.8 KB
Raw
title
bitsets

The stdlib_bitsets module

[TOC]

Introduction

The stdlib_bitsets module implements bitset types. A bitset is a compact representation of a sequence of bits binary values. It can equivalently be considered as a sequence of logical values or as a subset of the integers 0 ... bits-1. For example, the value 1110 can be considered as defining the subset of integers [1, 2, 3]. The bits are indexed from 0 to bits(bitset)-1. A bitset is used when space savings are critical in applications that require a large number of closely related logical values. It may also improve performance by reducing memory traffic. To implement bitsets the module defines three bitset types, multiple constants, a character string literal that can be read to and from strings and formatted files, a simple character string literal that can be read to and from strings, assignments, procedures, methods, and operators. Note that the module assumes two's complement integers, but all current Fortran 95 and later processors use such integers.

Note that the module defines a number of "binary" procedures, procedures with two bitset arguments. These arguments must be of the same type and should have the same number of bits. For reasons of performance the module does not enforce the bits constraint, but failure to obey that constraint results in undefined behavior. This undefined behavior includes undefined values for those bits that exceed the defined number of bits in the smaller bitset. The undefined behavior may also include a "segmentation fault" for attempting to address bits in the smaller bitset, beyond the defined number of bits. Other problems are also possible.

The module's constants

The module defines several public integer constants, almost all intended to serve as error codes in reporting problems through an optional stat argument. One constant, bits_kind is the integer kind value for indexing bits and reporting counts of bits. The other constants that are error codes are summarized below:

Error Code Summary
success No problems found
alloc_fault Failure with a memory allocation
array_size_invalid_error Attempt to define either negative bits or more than 64 bits in a bitset_64
char_string_invalid_error Invalid character found in a character string
char_string_too_large_error Character string was too large to be encoded in the bitset
char_string_too_small_error Character string was too small to hold the expected number of bits
index_invalid_error Index to a bitstring was less than zero or greater than the number of bits
integer_overflow_error Attempt to define an integer value bigger than huge(0_bits_kind)
read_failure Failure on a read statement
eof_failure An unexpected "End-of-File" on a read statement
write_failure Failure on a write statement

The stdlib_bitsets derived types

The stdlib_bitsets module defines three derived types, bitset_type, bitset_64, and bitset_large. bitset_type is an abstract type that serves as the ancestor of bitset_64 and bitset_large. bitset_type defines one method, bits, and all of its other methods are deferred to its extensions. bitset_64 is a bitset that can handle up to 64 bits. bitset_large is a bitset that can handle up huge(0_bits_kind) bits. All attributes of the bitset types are private. The various types each define a sequence of binary values: 0 or 1. In some cases it is useful to associate a logical value, test, for each element of the sequence, where test is .true. if the value is 1 and .false. otherwise. The number of such values in an entity of that type is to be termed, bits. The bits are ordered in terms of position, that, in turn, is indexed from 0 to bits-1. bitset_type is used only as a class to define entities that can be either a bitset_64 or a bitset_large. The syntax for using the types are:

class( [[stdlib_bitsets(module):bitset_type(type)]] ) :: variable

type( [[stdlib_bitsets(module):bitset_64(type)]] ) :: variable

and

type( [[stdlib_bitsets(module):bitset_large(type)]] ) :: variable

The bitset-literal

A bitset value may be represented as a bitset-literal-constant character string in source code or as a bitset-literal in formatted files and non-constant strings.

bitset-literal-constant is ' bitset-literal ' or " bitset-literal "

bitset-literal is bitsize-literal binary-literal

bitsize-literal is S digit [ digit ] ...

binary-literal is B binary-digit [ binary-digit ] ...

digit is 0 or 1 or 2 or 3 or 4 or 5 or 6 or 7 or 8 or 9

binary-digit is 0 or 1

The bitset-literal consists of two parts: a bitsize-literal and a binary-literal. The sequence of decimal digits that is part of the bitsize-literal is interpreted as the decimal value of bits. The binary-literal value is interpreted as a sequence of bit values and there must be as many binary digits in the literal as there are bits. The sequence of binary digits are treated as if they were an unsigned integer with the i-th digit corresponding to the bits-i bit position.

The binary-literal

In defining the bitset-literal we also defined a binary-literal. While not suitable for file I/0, the binary-literal is suitable for transfer to and from character strings. In that case the length of the string is the number of bits and all characters in the string must be either "0" or "1".

Summary of the module's operations

The stdlib_bitsets module defines a number of operations:

  • "unary" methods of class bitset_type,
  • "binary" procedure overloads of type bitset_64 or bitset_large,
  • assignments, and
  • "binary" comparison operators of type bitset_64 or bitset_large.

Each category will be discussed separately.

Table of the bitset_type methods

The bitset_type class has a number of methods. All except one, bits, are deferred. The methods consist of all procedures with one argument of class bitset_type. The procedures with two arguments of type bitset_64 or bitset_large are not methods and are summarized in a separate table of procedures. The methods are summarized below:

Method name Class Summary
all function .true. if all bits are 1, .false. otherwise
any function .true. if any bits are 1, .false. otherwise
bit_count function returns the number of bits that are 1
bits function returns the number of bits in the bitset
clear subroutine sets a sequence of one or more bits to 0
flip subroutine flips the value of a sequence of one or more bits
from_string subroutine reads the bitset from a string treating it as a binary literal
init subroutine creates a new bitset of size bits with no bits set
input subroutine reads a bitset from an unformatted I/O unit
none function .true. if no bits are 1, .false. otherwise
not subroutine performs a logical not operation on all the bits
output subroutine writes a bitset to an unformatted I/O unit
read_bitset subroutine reads a bitset from a bitset literal in a character string or formatted I/O unit
set subroutine sets a sequence of one or more bits to 1
test function .true. if the bit at pos is 1, .false. otherwise
to_string subroutine represents the bitset as a binary literal
value function 1 if the bit at pos is 1, 0 otherwise
write_bitset subroutine writes a bitset as a bitset literal to a character string or formatted I/O unit

Table of the non-member procedure overloads

The procedures with two arguments of type bitset_large or bitset_64 must have both arguments of the same known type which prevents them from being methods. The bitwise "logical" procedures, and, and_not, or, and xor also require that the two bitset arguments have the same number of bits, otherwise the results are undefined. These procedures are summarized in the following table:

Procedure name Class Summary
and elemental subroutine Sets self to the bitwise and of the original bits in self and set2
and_not elemental subroutine Sets self to the bitwise and of the original bits in self and the negation of set2
extract subroutine creates a new bitset, new, from a range in old
or elemental subroutine Sets self to the bitwise or of the original bits in self and set2
xor elemental subroutine Sets self to the bitwise exclusive or of the original bits in self and set2

Assignments

The module uses the intrinsic assignment operation, =, to create a duplicate of an original bitset. It additionally defines assignments to and from rank one arrays of logical type of kinds int8, int16, int32, and int64. In the assignment to and from logical arrays array index, i, is mapped to bit position, pos=i-1, and .true. is mapped to a set bit, and .false. is mapped to an unset bit.

Example

{!example/bitsets/example_bitsets_assignment.f90!}

Table of the non-member comparison operations

The comparison operators with two arguments of type bitset_large or bitset_64 must have both arguments of the same known type which prevents them from being methods. The operands must also have the same number of bits otherwise the results are undefined. These operators are summarized in the following table:

Operator Description
==, .eq. .true. if all bits in set1 and set2 have the same value, .false. otherwise
/=, .ne. .true. if any bits in set1 and set2 differ in value, .false. otherwise
>, .gt. .true. if the bits in set1 and set2 differ in value and the highest order differing bit is 1 in set1 and 0 in set2, .false. otherwise
>=, .ge. .true. if the bits in set1 and set2 are the same or the highest order differing bit is 1 in set1 and 0 in set2, .false. otherwise
<, .lt. .true. if the bits in set1 and set2 differ in value and the highest order differing bit is 0 in set1 and 1 in set2, .false. otherwise
<=, .le. .true. if the bits in set1 and set2 are the same or the highest order differing bit is 0 in set1 and 1 in set2, .false. otherwise

Specification of the stdlib_bitsets methods and procedures

all - determine whether all bits are set in self

Status

Experimental

Description

Determines whether all bits are set to 1 in self.

Syntax

result = self % [[bitset_type(type):all(bound)]] ()

Class

Elemental function.

Argument

self: shall be a scalar expression of class bitset_type. It is an intent(in) argument.

Result value

The result is a default logical scalar. The result is .true. if all bits in self are set, otherwise it is .false..

Example

{!example/bitsets/example_bitsets_all.f90!}

and - bitwise and of the bits of two bitsets

Status

Experimental

Description

Sets the bits in set1 to the bitwise and of the original bits in set1 and set2. Note that set1 and set2 must have the same number of bits, otherwise the result is undefined.

Syntax

call [[stdlib_bitsets(module):and(interface)]] (set1, set2)

Class

Elemental subroutine.

Arguments

set1: shall be a bitset_64 or bitset_large scalar variable. It is an intent(inout) argument. On return the values of the bits in set1 are the bitwise and of the original bits in set1 with the corresponding bits in set2.

set2: shall be a scalar expression of the same type as set1. It is an intent(in) argument. Note that set2 must also have the same number of bits as set1.

Example

{!example/bitsets/example_bitsets_and.f90!}

and_not - Bitwise and of one bitset with the negation of another

Status

Experimental

Description

Sets the bits of set1 to bitwise and of the bits of set1 with the bitwise negation of the corresponding bits of set2. Note that set1 and set2 must have the same number of bits, otherwise the result is undefined.

Syntax

call [[stdlib_bitsets(module):and_not(interface)]] (set1, set2)

Class

Elemental subroutine.

Arguments

set1: shall be a scalar bitset_64 or bitset_large variable. It is an intent(inout) argument. On return the values of the bits in set1 are the bitwise and of the original bits in set1 with the corresponding negation of the bits in set2.

set2: shall be a scalar expression of the same type as set1. It is an intent(in) argument. Note that it should also have the same number of bits as set1, otherwise the result is undefined.

Example

{!example/bitsets/example_bitsets_and_not.f90!}

any - determine whether any bits are set

Status

Experimental

Description

Determines whether any bits are set in self.

Syntax

result = self % [[bitset_type(type):any(bound)]] ()

Class

Elemental function.

Argument

self: shall be a scalar expression of class bitset_type. It is an intent(in) argument.

Result value

The result is a default logical scalar. The result is .true. if any bits in self are set, otherwise it is .false..

Example

{!example/bitsets/example_bitsets_any.f90!}

bit_count - return the number of bits that are set

Status

Experimental

Description

Returns the number of bits that are set to one in self.

Syntax

result = self % [[bitset_type(type):bit_count(bound)]] ()

Class

Elemental function.

Argument

self: shall be a scalar expression of class bitset_type. It is an intent(in) argument.

Result value

The result is an integer scalar of kind bits_kind, equal to the number of bits that are set in self.

Example

{!example/bitsets/example_bitsets_bit_count.f90!}

bits - returns the number of bits

Status

Experimental

Description

Reports the number of bits in self.

Syntax

result = self % [[bitset_type(type):bits(bound)]] ()

Class

Elemental function.

Argument

self: shall be a scalar expression of class bitset_type. It is an intent(in) argument.

Result value

The result is an integer scalar of kind bits_kind, equal to the number of defined bits in self.

Example

{!example/bitsets/example_bitsets_bits.f90!}

clear - clears a sequence of one or more bits

Status

Experimental

Description

  • If only pos is present, clears the bit with position pos in self.

  • If start_pos and end_pos are present with end_pos >= start_pos clears the bits with positions from start_pos to end_pos in self.

  • if start_pos and end_pos are present with end_pos < start_pos self is unmodified.

Note: Positions outside the range 0 to bits(set) -1 are ignored.

Syntax

call self % [[bitset_type(type):clear(bound)]] (pos)

or

call self % [[bitset_type(type):clear(bound)]] (start_pos, end_pos)

Class

Elemental subroutine

Arguments

self: shall be a scalar variable of class bitset_type. It is an intent(inout) argument.

pos: shall be a scalar integer expression of kind bits_kind. It is an intent(in) argument.

start_pos: shall be a scalar integer expression of kind bits_kind. It is an intent(in) argument.

end_pos: shall be a scalar integer expression of kind bits_kind. It is an intent(in) argument.

Example

{!example/bitsets/example_bitsets_clear.f90!}

extract - create a new bitset from a range in an old bitset

Status

Experimental

Description

Creates a new bitset, new, from a range, start_pos to stop_pos, in bitset old. If start_pos is greater than stop_pos the new bitset is empty. If start_pos is less than zero or stop_pos is greater than bits(old)-1 then if status is present it has the value index_invalid_error, otherwise processing stops with an informative message.

Syntax

call [[stdlib_bitsets(module):extract(interface)]] (new, old, start_pos, stop_pos, status )

Class

Subroutine

Arguments

new: shall be a scalar bitset_64 or bitset_large variable. It is an intent(out) argument. It will be the new bitset.

old: shall be a scalar expression of the same type as new. It is an intent(in) argument. It will be the source bitset.

start_pos: shall be a scalar integer expression of the kind bits_kind. It is an intent(in) argument.

stop_pos: shall be a scalar integer expression of the kind bits_kind. It is an intent(in) argument.

status (optional): shall be a scalar default integer variable. It is an intent(out) argument. If present it shall have one of the values:

  • success - no problems found

  • index_invalid_error - start_pos was less than zero or stop_pos was greater than bits(old)-1.

Example

{!example/bitsets/example_bitsets_extract.f90!}

flip - flip the values of a sequence of one or more bits

Status

Experimental

Description

Flip the values of a sequence of one or more bits.

  • If only pos is present flip the bit value with position pos in

    self.

  • If start_pos and end_pos are present with end_pos >= start_pos flip the bit values with positions from start_pos to end_pos in self.

  • If end_pos < start_pos then self is unmodified.

Syntax

call self % [[bitset_type(type):flip(bound)]] (pos)

or

call self % [[bitset_type(type):flip(bound)]] (start_pos, end_pos)

Class

Elemental subroutine.

Arguments

self: shall be a scalar class bitset_type variable It is an intent(inout) argument.

pos: shall be a scalar integer expression of kind bits_kind. It is an intent(in) argument.

start_pos: shall be a scalar integer expression of kind bits_kind. It is an intent(in) argument.

end_pos: shall be a scalar integer expression of kind bits_kind. It is an intent(in) argument.

Example

{!example/bitsets/example_bitsets_flip.f90!}

from_string - initializes a bitset from a binary literal

Status

Experimental

Description

Initializes the bitset self from string, treating string as a binary literal.

Syntax

call self % [[bitset_type(type):from_string(bound)]] (string[, status])

Class

Subroutine

Arguments

self: shall be a scalar class bitset_type variable. It is an intent(out) argument.

string: shall be a scalar default character expression. It is an intent(in) argument. It shall consist only of the characters "0", and "1".

status (optional): shall be a scalar default integer variable. It is an intent(out) argument. If present, on return its value shall be one of the error codes defined in this module. If absent, and its value would not have been success, then processing will stop with an informative text as its stop code. It shall have one of the error codes:

  • success - if no problems were found,

  • alloc_fault - if allocation of the bitset failed

  • char_string_too_large_error - if string was too large, or

  • char_string_invalid_error - if string had an invalid character.

Example

{!example/bitsets/example_bitsets_from_string.f90!}

init - bitset_type initialization routines

Status

Experimental

Description

bitset_type initialization routine.

Syntax

call self % [[bitset_type(type):init(bound)]] (bits [, status])

Class

Subroutine.

Arguments

self: shall be a scalar bitset_64 or bitset_large variable. It is an intent(out) argument.

bits: shall be a scalar integer expression of kind bits_kind. It is an intent(in) argument that if present specifies the number of bits in set. A negative value, or a value greater than 64 if self is of type bitset_64, is an error.

status (optional): shall be a scalar default integer variable. It is an intent(out) argument that, if present, returns an error code indicating any problem found in processing init, and if absent and an error was found result in stopping processing with an informative stop code. It can have any of the following error codes:

  • success - no problem found

  • alloc_fault - self was of type bitset_large and memory allocation failed

  • array_size_invalid_error - bits was present with either a negative value, or a value greater than 64 when self was of type bitset_64.

Example

{!example/bitsets/example_bitsets_init.f90!}

input - reads a bitset from an unformatted file

Status

Experimental

Description

Reads a bitset from its binary representation in an unformatted file.

Syntax

call self % [[bitset_type(type):input(bound)]] (unit [, status])

Class

Subroutine

Arguments

self: shall be a scalar variable of class bitset_64 or bitset_large. It is an intent(out) argument.

unit: shall be a scalar default integer expression. It is an intent(in) argument. Its value must be that of a logical unit number for an open unformatted file with read or readwrite access positioned at the start of a bitset value written by a bitset_type output subroutine by the same processor.

status (optional): shall be a scalar default integer variable. If present its value shall be of one of the error codes defined in this module. If absent and it would have had a value other than success processing will stop with an informative stop code. Allowed error code values for this status are:

  • success - no problem found

  • alloc_fault - self was of type bitset_large and allocation of memory failed.

  • array_size_invalid_error - if the number of bits read from unit is either negative or greater than 64, if class of self is bitset_64.

  • read_failure - failure during a read statement

Example

{!example/bitsets/example_bitsets_input.f90!}

none - determines whether no bits are set

Status

Experimental

Description

Determines whether no bits are set in self.

Syntax

result = self % [[bitset_type(type):none(bound)]] ()

Class

Elemental function.

Argument

self: shall be a scalar expression of class bitset_type. It is an intent(in) argument.

Result value

The result is a default logical scalar. The result is .true. if no bits in self are set, otherwise it is .false..

Example

{!example/bitsets/example_bitsets_none.f90!}

not - Performs the logical complement on a bitset

Status

Experimental

Description

Performs the logical complement on the bits of self.

Syntax

call self % [[bitset_type(type):not(bound)]] ()

Class

Elemental subroutine.

Argument

self shall be a scalar variable of class bitset_type. It is an intent(inout) argument. On return its bits shall be the logical complement of their values on input.

Example

{!example/bitsets/example_bitsets_not.f90!}

or - Bitwise OR of the bits of two bitsets

Status

Experimental

Description

Replaces the original bits of set1 with the bitwise or of those bits with the bits of set2. Note set1 and set2 must have the same number of bits, otherwise the result is undefined.

Syntax

call [[stdlib_bitsets(module):or(interface)]] (set1, set2)

Class

Elemental subroutine.

Arguments

set1: shall be a scalar bitset_64 or bitset_large variable. It is an intent(inout) argument. On return the values of the bits in setf are the bitwise or of the original bits in set1 with the corresponding bits in set2.

set2: shall be a scalar expression of the same type as set1. It is an intent(in) argument. Note bits(set2) must equal bits(set1) otherwise the results are undefined.

Example

{!example/bitsets/example_bitsets_or.f90!}

output - Writes a binary representation of a bitset to a file

Status

Experimental

Description

Writes a binary representation of a bitset to an unformatted file.

Syntax

call self % [[bitset_type(type):output(bound)]] (unit[, status])

Class

Subroutine.

Arguments

self: shall be a scalar expression of class bitset_64 or bitset_large. It is an intent(in) argument.

unit: shall be a scalar default integer expression. It is an intent(in) argument. Its value must be that of an I/O unit number for an open unformatted file with write or readwrite access.

status (optional): shall be a scalar default integer variable. It is an intent(out) argument. If present on return it will have the value of success or write_failure. If absent and it would not have the value of success then processing will stop with an informative stop code. The two code values have the meaning:

  • success - no problem found

  • write_failure - a failure occurred in a write statement.

Example

{!example/bitsets/example_bitsets_output.f90!}

read_bitset - initializes self with the value of a bitset_literal

Status

Experimental

Description

Reads a bitset-literal and initializes self with the corresponding value.

Syntax

call self % [[bitset_type(type):read_bitset(bound)]] (string[, status])

or

call self % [[bitset_type(type):read_bitset(bound)]] (unit[, advance, status])

Class

Subroutine

Arguments

self: shall be a scalar variable of class bitset_type. It is an intent(out) argument. Upon a successful return it is initialized with the value of a bitset-literal.

string (optional): shall be a scalar default character expression. It is an intent(in) argument. It will consist of a left justified bitset-literal, terminated by either the end of the string or a blank.

unit (optional): shall be a scalar default integer expression. It is an intent(in) argument. Its value must be that of an I/O unit number for an open formatted file with read or readwrite access positioned at the start of a bitset-literal.

advance (optional): shall be a scalar default character expression. It is an intent(in) argument. It is the advance specifier for the final read of unit. If present it should have the value 'yes' or 'no'. If absent it has the default value of 'yes'.

status (optional): shall be a scalar default integer variable. It is an intent(out) argument. If present on return it shall have the value of one of the error codes of this module. If absent and it would not have had the value success processing will stop with a message as its error code. The possible error codes are:

  • success - no problems found;

  • alloc_fault - if self is of class bitset_large and allocation of the bits failed;

  • array_size_invalid_error - if the bitset-literal has a bits value greater than 64 and self is of class bitset_64;

  • char_string_invalid_error - if the bitset-literal has an invalid character;

  • char_string_too_small_error - if string ends before all the bits are read;

  • eof_failure - if a read statement reached an end-of-file before completing the read of the bitset literal,

  • integer_overflow_error - if the bitset-literal has a bits value larger than huge(0_bits_kind); or

  • read_failure - if a read statement failed.

Example

{!example/bitsets/example_bitsets_read_bitset.f90!}

set - sets a sequence of one or more bits to 1

Status

Experimental

Description

Sets a sequence of one or more bits in self to 1.

  • If start_pos and end_pos are absent sets the bit at position pos in self to 1.

  • If start_pos and end_pos are present with end_pos >= start_pos set the bits at positions from start_pos to end_pos in self to 1.

  • If start_pos and end_pos are present with end_pos < start_pos self is unchanged.

  • Positions outside the range 0 to bits(self) are ignored.

Syntax

call self % [[bitset_type(type):set(bound)]] (POS)

or

call self % [[bitset_type(type):set(bound)]] (START_POS, END_POS)

Class

Elemental subroutine

Arguments

self: shall be a scalar variable of class bitset_type. It is an intent(inout) argument.

pos (optional): shall be a scalar integer expression of kind bits_kind. It is an intent(in) argument.

start_pos (optional): shall be a scalar integer expression of kind bits_kind. It is an intent(in) argument.

end_pos (optional): shall be a scalar integer expression of kind bits_kind. It is an intent(in) argument.

Example

{!example/bitsets/example_bitsets_set.f90!}

test - determine whether a bit is set

Status

Experimental

Descriptions

Determine whether the bit at position pos is set to 1 in self.

Syntax

result = self % [[bitset_type(type):test(bound)]] (pos)

Class

Elemental function.

Arguments

self: shall be a scalar expression of class bitset_type. It is an intent(in) argument.

pos: shall be a scalar integer expression of kind bits_kind. It is an intent(in) argument.

Result value

The result is a default logical scalar. The result is .true. if the bit at pos in self is set, otherwise it is .false.. If pos is outside the range 0... bits(self)-1 the result is .false..

Example

{!example/bitsets/example_bitsets_test.f90!}

to_string - represent a bitset as a binary literal

Status

Experimental

Description

Represents the value of self as a binary literal in string.

Syntax

call self % [[bitset_type(type):to_string(bound)]] (string[, status])

Class

Subroutine

Arguments

self: shall be a scalar expression of class bitset_type. It is an intent(in) argument.

string: shall be a scalar default character variable of allocatable length. It is an intent(out) argument. On return it shall have a binary-literal representation of the bitset self.

status (optional): shall be a scalar default integer variable. It is an intent(out) argument. If present it shall have either the value success or alloc_fault. If absent and it would have had the value alloc_fault then processing will stop with an informative test as the stop code. The values have the following meanings:

success - no problem found.

alloc_fault - allocation of string failed.

Example

{!example/bitsets/example_bitsets_to_string.f90!}

value - determine the value of a bit

Status

Experimental

Description

Determines the value of the bit at position, pos, in self.

Syntax

result = self % [[bitset_type(type):value(bound)]] (pos)

Class

Elemental function.

Arguments

self: shall be a scalar expression of class bitset_type. It is an intent(in) argument.

pos: shall be a scalar integer expression of kind bits_kind. It is an intent(in) argument.

Result value

The result is a default integer scalar. The result is one if the bit at pos in self is set, otherwise it is zero. If pos is outside the range 0... bits(set)-1 the result is zero.

Example

{!example/bitsets/example_bitsets_value.f90!}

write_bitset - writes a bitset-literal

Status

Experimental

Description

Writes a bitset-literal representing self's current value to a character string or formatted file.

Syntax

call self % [[bitset_type(type):write_bitset(bound)]] (string[, status])

or

call self % [[bitset_type(type):write_bitset(bound)]] (unit[, advance, status])

Class

Subroutine

Arguments

self: shall be a scalar expression of class bitset_type. It is an intent(in) argument.

string (optional): shall be a scalar default character variable of allocatable length. It is an intent(out) argument.

unit (optional): shall be a scalar default logical expression. It is an intent(in) argument. Its value must be that of a I/O unit number for an open formatted file with write or readwrite access.

advance (optional): shall be a scalar default character expression. It is an intent(in) argument. It is the advance specifier for the write to unit. If present it must have the value 'yes' or 'no'. It has the default value of 'yes'.

  • if advance is not present or is present with a value of 'no' then the bitset's bitset-literal is written to unit followed by a blank, and the current record is not advanced.

  • If advance is present with a value of 'yes' then the bitset's bitset-literal is written to unit and the record is immediately advanced.

status (optional): shall be a scalar default integer variable. It is an intent(out) argument. If present on return it shall have the value of one of the module's error codes. If absent and a problem was found processing will stop with an informative stop code. It may have the following error code values:

  • success - no problem was found

  • alloc_fault - allocation of the string failed

  • write_failure - the write to the unit failed

Example

{!example/bitsets/example_bitsets_write_bitset.f90!}

xor - bitwise exclusive or

Status

Experimental

Description

Replaces set1's bitset with the bitwise exclusive or of the original bits of set1 and set2. Note set1 and set2 must have the samee number of bits, otherwise the result is undefined.

Syntax

result = [[stdlib_bitsets(module):xor(interface)]] (set1, set2)

Class

Elemental subroutine

Arguments

set1: shall be a scalar bitset_64 or bitset_large variable. It is an intent(inout) argument. On return the values of the bits in set1 are the bitwise exclusive or of the original bits in set1 with the corresponding bits in set2.

set2 shall be a scalar expression of the same type as set1. It is an intent(in) argument. Note set1 and set2 must have the samee number of bits, otherwise the result is undefined.

Example

{!example/bitsets/example_bitsets_xor.f90!}

Specification of the stdlib_bitsets operators

== - compare two bitsets to determine whether the bits have the same value

Status

Experimental

Description

Returns .true. if all bits in set1 and set2 have the same value, .false. otherwise.

Syntax

result = set1 [[stdlib_bitsets(module):==(interface)]] set2

or

result = set1 .EQ. set2

Class

Elemental operator

Arguments

set1: shall be a scalar bitset_64 or bitset_large expression. It is an intent(in) argument.

set2: shall be a scalar expression of the same type as self. It will have the same number of bits as set1. It is an intent(in) argument.

Result value

The result is a default logical scalar. The result is .true. if the bits in both bitsets are set to the same value, otherwise the result is .false..

Example

{!example/bitsets/example_bitsets_equality.f90!}

/= - compare two bitsets to determine whether any bits differ in value

Status

Experimental

Description

Returns .true. if any bits in self and set2 differ in value, .false. otherwise.

Syntax

result = set1 [[stdlib_bitsets(module):/=(interface)]] set2

or

result = set1 .NE. set2

Class

Elemental function

Arguments

set1: shall be a scalar bitset_64 or bitset_large expression. It is an intent(in) argument.

set2: shall be a scalar expression of the same type as self. It will have the same number of bits as set1. It is an intent(in) argument.

Result value

The result is a default logical scalar. The result is .true. if any bits in both bitsets differ, otherwise the result is .false..

Example

{!example/bitsets/example_bitsets_inequality.f90!}

>= - compare two bitsets to determine whether the first is greater than or equal to the second

Status

Experimental

Description

Returns .true. if the bits in set1 and set2 are the same or the highest order different bit is set to 1 in set1 and to 0 in set2, .false.. otherwise. The sets must be the same size otherwise the results are undefined.

Syntax

result = set1 [[stdlib_bitsets(module):>=(interface)]] set2

or

result = set1 .GE. set2

Class

Elemental operator

Arguments

set1: shall be a scalar bitset_64 or bitset_large expression. It is an intent(in) argument.

set2: shall be a scalar expression of the same type as self. It will have the same number of bits as set1. It is an intent(in) argument.

Result value

The result is a default logical scalar. The result is .true. if the bits in set1 and set2 are the same or the highest order different bit is set to 1 in set1 and to 0 in set2, .false. otherwise.

Example

{!example/bitsets/example_bitsets_ge.f90!}

> - compare two bitsets to determine whether the first is greater than the other

Status

Experimental

Description

Returns .true. if the bits in set1 and set2 differ and the highest order different bit is set to 1 in set1 and to 0 in set2, .false. otherwise. The sets must be the same size otherwise the results are undefined.

Syntax

result = set1 [[stdlib_bitsets(module):>(interface)]] set2

or

result = set1 .GT. set2

Class

Elemental operator

Arguments

set1: shall be a scalar bitset_64 or bitset_large expression. It is an intent(in) argument.

set2: shall be a scalar expression of the same type as self. It will have the same number of bits as set1. It is an intent(in) argument.

Result value

The result is a default logical scalar. The result is .true. if the bits in set1 and set2 differ and the highest order different bit is set to 1 in set1 and to 0 in set2, .false. otherwise.

Example

{!example/bitsets/example_bitsets_gt.f90!}

<= - compare two bitsets to determine whether the first is less than or equal to the other

Status

Experimental

Description

Returns .true. if the bits in set1 and set2 are the same or the highest order different bit is set to 0 in set1 and to 1 in set2, .false. otherwise. The sets must be the same size otherwise the results are undefined.

Syntax

result = set1 [[stdlib_bitsets(module):<=(interface)]] set2

or

result = set1 .LE. set2

Class

Elemental operator

Arguments

set1: shall be a scalar bitset_64 or bitset_large expression. It is an intent(in) argument.

set2: shall be a scalar expression of the same type as self. It will have the same number of bits as set1. It is an intent(in) argument.

Result value

The result is a default logical scalar. The result is .true. if the bits in set1 and set2 are the same or the highest order different bit is set to 0 in set1 and to 1 in set2, .false. otherwise.

Example

{!example/bitsets/example_bitsets_le.f90!}

< - compare two bitsets to determine whether the first is less than the other

Status

Experimental

Description

Returns .true. if the bits in set1 and set2 differ and the highest order different bit is set to 0 in set1 and to 1 in set2, .false. otherwise. The sets must be the same size otherwise the results are undefined.

Syntax

result = set1 [[stdlib_bitsets(module):<(interface)]] set2

or

`result = set1 .LT. set2

Class

Elemental operator

Arguments

set1: shall be a scalar bitset_64 or bitset_large expression. It is an intent(in) argument.

set2: shall be a scalar expression of the same type as self. It will have the same number of bits as set1. It is an intent(in) argument.

Result value

The result is a default logical scalar. The result is .true. if the bits in set1 and set2 differ and the highest order different bit is set to 0 in set1 and to 1 in set2, .false. otherwise.

Example

{!example/bitsets/example_bitsets_lt.f90!}