9.6. Bit String Functions and Operators

Bit String Functions and Operators

This section describes functions and operators for examining and manipulating bit strings, that is values of the types bit and bit varying. (While only type bit is mentioned in these tables, values of type bit varying can be used interchangeably.) Bit strings support the usual comparison operators shown in Comparison Operators, as well as the operators shown in Bit String Operators.

Operator Description Example(s)
`bit` `\|\|` `bit` bit Concatenation `B'10001' \|\| B'011'` 10001011
`bit` `&` `bit` bit Bitwise AND (inputs must be of equal length) `B'10001' & B'01101'` 00001
`bit` `\|` `bit` bit Bitwise OR (inputs must be of equal length) `B'10001' \| B'01101'` 11101
`bit` `#` `bit` bit Bitwise exclusive OR (inputs must be of equal length) `B'10001' # B'01101'` 11100
`~` `bit` bit Bitwise NOT `~ B'10001'` 01110
`bit` `<<` `integer` bit Bitwise shift left (string length is preserved) `B'10001' << 3` 01000
`bit` `>>` `integer` bit Bitwise shift right (string length is preserved) `B'10001' >> 2` 00100

Operator

Description

Example(s)

bit || bit bit

Concatenation

B'10001' || B'011' 10001011

bit & bit bit

Bitwise AND (inputs must be of equal length)

B'10001' & B'01101' 00001

bit | bit bit

Bitwise OR (inputs must be of equal length)

B'10001' | B'01101' 11101

bit # bit bit

Bitwise exclusive OR (inputs must be of equal length)

B'10001' # B'01101' 11100

~ bit bit

Bitwise NOT

~ B'10001' 01110

bit << integer bit

Bitwise shift left (string length is preserved)

B'10001' << 3 01000

bit >> integer bit

Bitwise shift right (string length is preserved)

B'10001' >> 2 00100

: Bit String Operators

Some of the functions available for binary strings are also available for bit strings, as shown in Bit String Functions.

Function Description Example(s)
`bit_count` ( `bit` ) bigint Returns the number of bits set in the bit string (also known as "popcount"). `bit_count(B'10111')` 4
`bit_length` ( `bit` ) integer Returns number of bits in the bit string. `bit_length(B'10111')` 5
`length` ( `bit` ) integer Returns number of bits in the bit string. `length(B'10111')` 5
`octet_length` ( `bit` ) integer Returns number of bytes in the bit string. `octet_length(B'1011111011')` 2
`overlay` ( `bits` `bit` `PLACING` `newsubstring` `bit` `FROM` `start` `integer` [`FOR` `count` `integer`] ) bit Replaces the substring of `bits` that starts at the `start`'th bit and extends for `count` bits with `newsubstring`. If `count` is omitted, it defaults to the length of `newsubstring`. `overlay(B'01010101010101010' placing B'11111' from 2 for 3)` 0111110101010101010
`position` ( `substring` `bit` `IN` `bits` `bit` ) integer Returns first starting index of the specified `substring` within `bits`, or zero if it's not present. `position(B'010' in B'000001101011')` 8
`substring` ( `bits` `bit` [`FROM` `start` `integer`] [`FOR` `count` `integer`] ) bit Extracts the substring of `bits` starting at the `start`'th bit if that is specified, and stopping after `count` bits if that is specified. Provide at least one of `start` and `count`. `substring(B'110010111111' from 3 for 2)` 00
`get_bit` ( `bits` `bit`, `n` `integer` ) integer Extracts `n`'th bit from bit string; the first (leftmost) bit is bit 0. `get_bit(B'101010101010101010', 6)` 1
`set_bit` ( `bits` `bit`, `n` `integer`, `newvalue` `integer` ) bit Sets `n`'th bit in bit string to `newvalue`; the first (leftmost) bit is bit 0. `set_bit(B'101010101010101010', 6, 0)` 101010001010101010

Function

Description

Example(s)

bit_count ( bit ) bigint

Returns the number of bits set in the bit string (also known as "popcount").

bit_count(B'10111') 4

bit_length ( bit ) integer

Returns number of bits in the bit string.

bit_length(B'10111') 5

length ( bit ) integer

Returns number of bits in the bit string.

length(B'10111') 5

octet_length ( bit ) integer

Returns number of bytes in the bit string.

octet_length(B'1011111011') 2

overlay ( bits bit PLACING newsubstring bit FROM start integer [FOR count integer] ) bit

Replaces the substring of bits that starts at the start'th bit and extends for count bits with newsubstring. If count is omitted, it defaults to the length of newsubstring.

overlay(B'01010101010101010' placing B'11111' from 2 for 3) 0111110101010101010

position ( substring bit IN bits bit ) integer

Returns first starting index of the specified substring within bits, or zero if it's not present.

position(B'010' in B'000001101011') 8

substring ( bits bit [FROM start integer] [FOR count integer] ) bit

Extracts the substring of bits starting at the start'th bit if that is specified, and stopping after count bits if that is specified. Provide at least one of start and count.

substring(B'110010111111' from 3 for 2) 00

get_bit ( bits bit, n integer ) integer

Extracts n'th bit from bit string; the first (leftmost) bit is bit 0.

get_bit(B'101010101010101010', 6) 1

set_bit ( bits bit, n integer, newvalue integer ) bit

Sets n'th bit in bit string to newvalue; the first (leftmost) bit is bit 0.

set_bit(B'101010101010101010', 6, 0) 101010001010101010

: Bit String Functions

In addition, it is possible to cast integral values to and from type bit. Casting an integer to bit(n) copies the rightmost n bits. Casting an integer to a bit string width wider than the integer itself will sign-extend on the left. Some examples:

44::bit(10)                    0000101100
44::bit(3)                     100
cast(-44 as bit(12))           111111010100
'1110'::bit(4)::integer        14

Note that casting to just "bit" means casting to bit(1), and so will deliver only the least significant bit of the integer.