parse_bin([::Type{T}], s::Union{AbstractString, AbstractVector{UInt8}}; filter=false, rev=false)

Convert an integer coded as a binary string (characters '1' and '0') to an unsigned integer.

The return type is T. If the first argument is omitted, then the return type is the narrowest suitable unsigned integer type.

The type T is typically a bits type UInt8, UInt16, Float64, etc., where the number of bits is a factor of 8. The largest unsigned integer type that is pre-generated from BitIntegers.jl is UInt1024. If T is omitted, a type that has not been pre-generated will be created.

Leading zeros are included in the calculation of the width of the resulting integer.

If filter is true, then characters other than '1' and '0' are ignored rather than raising an error. In this way, formatting, such as spaces, may be included in the input string.

If rev is true then the string is parsed from right to left rather than left to right. This incurrs no performance penalty.

Examples

julia> parse_bin(UInt8, "10001111") |> bitstring
"10001111"

julia> parse_bin(UInt8, "1000 1111")
ERROR: BoundsError: attempt to access 8-element Vector{UInt8} at index [9]

julia> parse_bin(UInt8, "10 00 11 11"; filter=true) |> bitstring
"10001111"

julia> parse_bin(UInt8, "10001111"; rev=true) |> bitstring
"11110001"

julia> parse_bin(Bool, "1")
true

Various input types are supported.

julia> s = "0001111100000100";

julia> parse_bin.(UInt16, (s, codeunits(s), collect(codeunits(s))))
(0x1f04, 0x1f04, 0x1f04)

The type parameter need not be a bitstype.

julia> x = parse_bin(Signed, s); (x, typeof(x))
(7940, Int16)

julia> x = parse_bin(Unsigned, s); (x, typeof(x))
(0x1f04, UInt16)

julia> x = parse_bin(Integer, s); (x, typeof(x))
(0x1f04, UInt16)

julia> x = parse_bin(BigInt, s); (x, typeof(x))
(7940, BigInt)

julia> parse_bin("1"^8; filter=true)
0xff

julia> parse_bin("1"^8 * " "^8; filter=true)
0x00ff

julia> parse_bin(UInt8, "1"^8 * " "^8; filter=true)
0xff

Extended help

Comparison with Base.parse

• parse_bin is roughly 5 to 10 faster.
• parse_bin can optionally ignore non-coding characters (formatting, for example) in the string
• parse_bin can accept AbstractVector{UInt8} as input.
• parse_bin can parse the characters in reverse order (at no performance cost).

Performance

Usually parse_bin is faster than Base.parse. The factor varies from about 5 to 10. However, for bit widths larger than about 650, parse_bin first parses the string as a BigInt using Base.parse and then converts to the appropriate fixed-wdith unsigned integer type.

parse_bin is often much faster if T is supplied because otherwise the return type cannot be inferred.

bstring(x::T; len::Union{Int, Nothing}, rev::Bool=true, sep::Int=0, pad::Bool=false)

Return a string giving the literal bit representation of x of a primitive type.

If rev is true (the default), then the string is reversed with respect to Base.bitstring.

If len is an Int, then the string will have length len. If len is greater than the bit-width of x then the string will be padded with '0'. If len is smaller than the bit-width of x, then upper bits will be truncated.

If pad is true, then the behavior of len is modified: At least all bits other than leading zeros are written. By setting len large enough you can write leading zeros as well.

If sep is greater than zero, a space is inserted every sep bits.

Examples

All bits are written by default. Most significant bit is leftmost.

julia> bstring(UInt16(11))
"1101000000000000"

If rev is false, the most significant bit is rightmost.

julia> bstring(UInt16(11); rev=false)
"0000000000001011"

If pad is true, leading zeros are omitted.

julia> bstring(UInt16(11); pad=true)
"1101"

julia> bstring(UInt16(11); pad=true, rev=false)
"1011"

len is the number of bits to write.

julia> bstring(UInt16(11); len=8)
"11010000"

julia> bstring(UInt16(11); len=8, rev=false)
"00001011"

julia> bstring(UInt16(11); len=3)
"110"

If len is passed and pad is true, the most significant bit will always be written.

julia> bstring(UInt16(11); len=3, pad=true)
"1101"

julia> bstring(UInt16(11); len=8, pad=true)
"11010000"

A space is inserted every sep bits.

julia> x = 0xf0ff00aa00; bstring(x; sep=8)
"00000000 01010101 00000000 11111111 00001111 00000000 00000000 00000000"

bstringview(v, [n])

Return an AbstractString view of v that represent a sequence of bits.

v may be of any type such that BitsBase.to_binary_char returns a character (i.e. does not throw an error) for each element of v as determined by Bits.bit.

Examples

julia> bstringview([1,0,1,1])
"1011"

julia> bstringview(UInt8(1 << 4 - 1))
"11110000"

julia> bstringview("110") # `bit` is implemented for binary strings.
"110"

julia> bsv = bstringview([true, false, true, false])
"1010"

julia> bsv[end]
'0': ASCII/Unicode U+0030 (category Nd: Number, decimal digit)

julia> bsv[end] = '1'
'1': ASCII/Unicode U+0031 (category Nd: Number, decimal digit)

julia> bsv
"1011"

julia> bsv[end] = false
false

If n is omitted, then the length of the string is the number of bits in v. For example, for v = UInt64(1), the length of the string is 64. For v::AbstractArray, the number of bits is length(v).

If n is zero, then the length of the string is the minimum number of bits needed to represent v. For example

Examples

julia> length(bstringview(UInt64(7)))
64

julia> length(bstringview(UInt64(7), 5))
5

julia> length(bstringview(UInt64(7), 0))
3

julia> bstringview(UInt64(7), 0)
"111"

julia> bstringview(UInt16(7))
"1110000000000000"

String(bstringview(v)) converts v to a `String.

julia> v = bstringview(UInt64(7), 0); vs = String(v); (v, vs)
("111", "111")

julia> typeof.((v, vs))
(BStringView{UInt64}, String)

normalize_bitstring(str::AbstractString)

Remove all characters (more precisely, code points) from str that are not one of '0' and '1', if such characters exist. Otherwise, return str unchanged.

randbitstring([rng = default_rng()], nbits::Integer, [dims])

Return a random string of '1's and '0's of length nbits.

The distribution is uniform over all such strings. If dims is given return an Array of random bitstrings with dimensions dims.

Examples

julia> import Random; rng = Random.seed!(10);

julia> randbitstring(rng, 10)
"1011110111"

See also randbitstring!.

randbitstring!([rng = default_rng()], a::AbstractArray, nbits::Integer)

Fill array a with random bitstrings.

is_bitstring(bit_str::Union{AbstractString, AbstractVector{UInt8}})

Return true if all characters in bit_str are either '0' or '1', otherwise false.

Examples

julia> is_bitstring("11001100")
true

julia> is_bitstring("1100 1100")
false

check_bitstring(bit_str::Union{AbstractString, AbstractVector{UInt8}})

Throw an ArgumentError unless all characters in bit_str are either '0' or '1'. Otherwise return nothing.

Examples

julia> check_bitstring("11001100")
true

julia> check_bitstring("1010010b")
ERROR: ArgumentError: Argument is not a bit string