Struct BitString

pub struct BitString(/* private fields */);

A representation of the BIT STRING ASN.1 data type. BitString is a wrapper around the bit_vec::BitVec type. Please refer to the BitVec documentation for using BitString in Rust. The following is documentation on how to use a BIT STRING in ASN.1.

A bit string has a tag which is universal class, number 3.

The first and final bits in a bit string are called the leading and trailing bits respectively.

• Note — This terminology is used in specifying the value notation and in defining encoding rules.

Notation

The following describes the notation used for defining BIT STRING types and values.

Type

BitStringType ::=
    BIT STRING
  | BIT STRING "{" NamedBitList "}"

NamedBitList ::=
    NamedBit
  | NamedBitList "," NamedBit

NamedBit ::=
    identifier "(" number ")"
  | identifier "(" DefinedValue ")"

The DefinedValue shall be a reference to a non-negative value of type integer.

The value of each number or DefinedValue appearing in the NamedBitList shall be different, and is the number of a distinguished bit in a bitstring value. The leading bit of the bit string is identified by the number zero, with succeeding bits having successive values.

• Note 1 — The order of the NamedBit production sequences in the NamedBitList is not significant.
• Note 2 — Since an identifier that appears within the NamedBitList cannot be used to specify the value associated with a NamedBit, the DefinedValue can never be misinterpreted as an IntegerValue. Therefore in the following case:

a INTEGER ::= 1
T1 ::= INTEGER { a(2) }
T2 ::= BIT STRING { a(3), b(a) }

The last occurrence of a in T2 denotes the value 1, as it cannot be a reference to the second nor the third occurrence of a.

The presence of a NamedBitList has no effect on the set of abstract values of this type. Values containing 1 bits other than the named bits are permitted.

When a NamedBitList is used in defining a bitstring type ASN.1 encoding rules are free to add (or remove) arbitrarily any trailing 0 bits to (or from) values that are being encoded or decoded. Application designers should therefore ensure that different semantics are not associated with such values which differ only in the number of trailing 0 bits.

Value

BitStringValue ::=
    bstring
  | hstring
  | "{" IdentifierList "}"
  | "{" "}"
  | CONTAINING Value

IdentifierList ::=
    identifier
  | IdentifierList "," identifier

Each identifier in BitStringValue shall be the same as an identifier in the BitStringType production sequence with which the value is associated.

If the bit string has named bits, the BitStringValue notation denotes a bit string value with ones in the bit positions specified by the numbers corresponding to the identifiers, and with all other bits zero.

• Note — For a BitStringType that has a NamedBitList, the "{" "}" production sequence in BitStringValue is used to denote the bit string which contains no one bits.

When using the bstring notation, the leading bit of the bitstring value is on the left, and the trailing bit of the bitstring value is on the right.

When using the hstring notation, the most significant bit of each hexadecimal digit corresponds to the leftmost bit in the bitstring.

• Note — This notation does not, in any way, constrain the way encoding rules place a bitstring into octets for transfer.

The hstring notation shall not be used unless the bitstring value consists of a multiple of four bits. The following are alternative notations for the same bitstring value. If the type was defined using a NamedBitList, the (single) trailing zero does not form part of the value, which is thus 15 bits in length. If the type was defined without a NamedBitList, the trailing zero does form part of the value, which is thus 16 bits in length.

'A98A'H
'1010100110001010'B

The CONTAINING alternative can only be used if there is a contents constraint on the bitstring type which includes CONTAINING. The Value shall then be value notation for a value of the Type in the ContentsConstraint (see Rec. ITU-T X.682 | ISO/IEC 8824-3, clause 11).

• Note — This value notation can never appear in a subtype constraint because Rec. ITU-T X.682 | ISO/IEC 8824-3, clause 11.3 forbids further constraints after a ContentsConstraint, and the above text forbids its use unless the governor has a ContentsConstraint.

The CONTAINING alternative shall be used if there is a contents constraint on the bitstring type which does not containENCODED BY.

Example

Use a bit string type to model binary data whose format and length are unspecified, or specified elsewhere, and whose length in bits is not necessarily a multiple of eight.

G3FacsimilePage ::= BIT STRING
-- a sequence of bits conforming to Rec. ITU-T T.4.
image G3FacsimilePage ::= '100110100100001110110'B
trailer BIT STRING ::= '0123456789ABCDEF'H
body1 G3FacsimilePage ::= '1101'B
body2 G3FacsimilePage ::= '1101000'B

• Note — that body1 and body2 are distinct abstract values because trailing 0 bits are significant (due to there being no NamedBitList in the definition of G3FacsimilePage).

Fixed size example

Use a bit string type with a size constraint to model the values of a fixed sized bit field.

BitField ::= BIT STRING (SIZE (12))
map1 BitField ::= '100110100100'B
map2 BitField ::= '9A4'H
map3 BitField ::= '1001101001'B -- Illegal - violates size constraint.

Bit map example

Use a bit string type to model the values of a bit map, an ordered collection of logical variables indicating whether a particular condition holds for each of a correspondingly ordered collection of objects.

DaysOfTheWeek ::= BIT STRING { sunday(0), monday (1), tuesday(2),
    wednesday(3), thursday(4), friday(5), saturday(6) } (SIZE (0..7))

sunnyDaysLastWeek1 DaysOfTheWeek ::= {sunday, monday, wednesday}
sunnyDaysLastWeek2 DaysOfTheWeek ::= '1101'B
sunnyDaysLastWeek3 DaysOfTheWeek ::= '1101000'B
sunnyDaysLastWeek4 DaysOfTheWeek ::= '11010000'B -- Illegal

• Note — If the bit string value is less than 7 bits long, then the missing bits indicate a cloudy day for those days, hence the first three values above have the same abstract value.

Fixed size bit map example

Use a bit string type to model the values of a bit map, a fixed-size ordered collection of logical variables indicating whether a particular condition holds for each of a correspondingly ordered collection of objects.

DaysOfTheWeek ::= BIT STRING { sunday(0), monday (1), tuesday(2),
    wednesday(3), thursday(4), friday(5), saturday(6) } (SIZE (7))

sunnyDaysLastWeek1 DaysOfTheWeek ::= {sunday, monday, wednesday}
sunnyDaysLastWeek2 DaysOfTheWeek ::= '1101'B -- Illegal -- violates size constraint.
sunnyDaysLastWeek3 DaysOfTheWeek ::= '1101000'B
sunnyDaysLastWeek4 DaysOfTheWeek ::= '11010000'B -- Illegal -- violates size constraint.

• Note — The first and third values have the same abstract value.

Example

Use a bit string type with named bits to model the values of a collection of related logical variables.

PersonalStatus ::= BIT STRING { married(0), employed(1), veteran(2), collegeGraduate(3) }
jane PersonalStatus ::= { married, employed, collegeGraduate }
alice PersonalStatus ::= '110100'B

• Note — that jane and alice have the same abstract values.

Implementations

impl BitString

pub fn new() -> Self

Instantiates a new empty instance of BitString.

pub fn from_bytes(input: &[u8]) -> Self

Instantiate a new instance of BitString from a byte slice.

Methods from Deref<Target = BitVec>

pub fn blocks(&self) -> Blocks<'_, B>

Iterator over the underlying blocks of data

pub fn storage(&self) -> &[B]

Exposes the raw block storage of this BitVec

Only really intended for BitSet.

pub unsafe fn storage_mut(&mut self) -> &mut Vec<B>

Exposes the raw block storage of this BitVec

Can probably cause unsafety. Only really intended for BitSet.

pub fn get(&self, i: usize) -> Option<bool>

Retrieves the value at index i, or None if the index is out of bounds.

Examples

use bit_vec::BitVec;

let bv = BitVec::from_bytes(&[0b01100000]);
assert_eq!(bv.get(0), Some(false));
assert_eq!(bv.get(1), Some(true));
assert_eq!(bv.get(100), None);

// Can also use array indexing
assert_eq!(bv[1], true);

pub fn set(&mut self, i: usize, x: bool)

Sets the value of a bit at an index i.

Panics

Panics if i is out of bounds.

Examples

use bit_vec::BitVec;

let mut bv = BitVec::from_elem(5, false);
bv.set(3, true);
assert_eq!(bv[3], true);

pub fn set_all(&mut self)

Sets all bits to 1.

Examples

use bit_vec::BitVec;

let before = 0b01100000;
let after  = 0b11111111;

let mut bv = BitVec::from_bytes(&[before]);
bv.set_all();
assert_eq!(bv, BitVec::from_bytes(&[after]));

pub fn negate(&mut self)

Flips all bits.

Examples

use bit_vec::BitVec;

let before = 0b01100000;
let after  = 0b10011111;

let mut bv = BitVec::from_bytes(&[before]);
bv.negate();
assert_eq!(bv, BitVec::from_bytes(&[after]));

pub fn union(&mut self, other: &BitVec<B>) -> bool

👎Deprecated since 0.7.0: Please use the ‘or’ function instead

Calculates the union of two bitvectors. This acts like the bitwise or function.

Sets self to the union of self and other. Both bitvectors must be the same length. Returns true if self changed.

Panics

Panics if the bitvectors are of different lengths.

Examples

use bit_vec::BitVec;

let a   = 0b01100100;
let b   = 0b01011010;
let res = 0b01111110;

let mut a = BitVec::from_bytes(&[a]);
let b = BitVec::from_bytes(&[b]);

assert!(a.union(&b));
assert_eq!(a, BitVec::from_bytes(&[res]));

pub fn intersect(&mut self, other: &BitVec<B>) -> bool

👎Deprecated since 0.7.0: Please use the ‘and’ function instead

Calculates the intersection of two bitvectors. This acts like the bitwise and function.

Sets self to the intersection of self and other. Both bitvectors must be the same length. Returns true if self changed.

Panics

Panics if the bitvectors are of different lengths.

Examples

use bit_vec::BitVec;

let a   = 0b01100100;
let b   = 0b01011010;
let res = 0b01000000;

let mut a = BitVec::from_bytes(&[a]);
let b = BitVec::from_bytes(&[b]);

assert!(a.intersect(&b));
assert_eq!(a, BitVec::from_bytes(&[res]));

pub fn or(&mut self, other: &BitVec<B>) -> bool

Calculates the bitwise or of two bitvectors.

Sets self to the union of self and other. Both bitvectors must be the same length. Returns true if self changed.

Panics

Panics if the bitvectors are of different lengths.

Examples

use bit_vec::BitVec;

let a   = 0b01100100;
let b   = 0b01011010;
let res = 0b01111110;

let mut a = BitVec::from_bytes(&[a]);
let b = BitVec::from_bytes(&[b]);

assert!(a.or(&b));
assert_eq!(a, BitVec::from_bytes(&[res]));

pub fn and(&mut self, other: &BitVec<B>) -> bool

Calculates the bitwise and of two bitvectors.

Sets self to the intersection of self and other. Both bitvectors must be the same length. Returns true if self changed.

Panics

Panics if the bitvectors are of different lengths.

Examples

use bit_vec::BitVec;

let a   = 0b01100100;
let b   = 0b01011010;
let res = 0b01000000;

let mut a = BitVec::from_bytes(&[a]);
let b = BitVec::from_bytes(&[b]);

assert!(a.and(&b));
assert_eq!(a, BitVec::from_bytes(&[res]));

pub fn difference(&mut self, other: &BitVec<B>) -> bool

Calculates the difference between two bitvectors.

Sets each element of self to the value of that element minus the element of other at the same index. Both bitvectors must be the same length. Returns true if self changed.

Panics

Panics if the bitvectors are of different length.

Examples

use bit_vec::BitVec;

let a   = 0b01100100;
let b   = 0b01011010;
let a_b = 0b00100100; // a - b
let b_a = 0b00011010; // b - a

let mut bva = BitVec::from_bytes(&[a]);
let bvb = BitVec::from_bytes(&[b]);

assert!(bva.difference(&bvb));
assert_eq!(bva, BitVec::from_bytes(&[a_b]));

let bva = BitVec::from_bytes(&[a]);
let mut bvb = BitVec::from_bytes(&[b]);

assert!(bvb.difference(&bva));
assert_eq!(bvb, BitVec::from_bytes(&[b_a]));

pub fn xor(&mut self, other: &BitVec<B>) -> bool

Calculates the xor of two bitvectors.

Sets self to the xor of self and other. Both bitvectors must be the same length. Returns true if self changed.

Panics

Panics if the bitvectors are of different length.

Examples

use bit_vec::BitVec;

let a   = 0b01100110;
let b   = 0b01010100;
let res = 0b00110010;

let mut a = BitVec::from_bytes(&[a]);
let b = BitVec::from_bytes(&[b]);

assert!(a.xor(&b));
assert_eq!(a, BitVec::from_bytes(&[res]));

pub fn nand(&mut self, other: &BitVec<B>) -> bool

Calculates the nand of two bitvectors.

Sets self to the nand of self and other. Both bitvectors must be the same length. Returns true if self changed.

Panics

Panics if the bitvectors are of different length.

Examples

use bit_vec::BitVec;

let a   = 0b01100110;
let b   = 0b01010100;
let res = 0b10111011;

let mut a = BitVec::from_bytes(&[a]);
let b = BitVec::from_bytes(&[b]);

assert!(a.nand(&b));
assert_eq!(a, BitVec::from_bytes(&[res]));

pub fn nor(&mut self, other: &BitVec<B>) -> bool

Calculates the nor of two bitvectors.

Sets self to the nor of self and other. Both bitvectors must be the same length. Returns true if self changed.

Panics

Panics if the bitvectors are of different length.

Examples

use bit_vec::BitVec;

let a   = 0b01100110;
let b   = 0b01010100;
let res = 0b10001001;

let mut a = BitVec::from_bytes(&[a]);
let b = BitVec::from_bytes(&[b]);

assert!(a.nor(&b));
assert_eq!(a, BitVec::from_bytes(&[res]));

pub fn xnor(&mut self, other: &BitVec<B>) -> bool

Calculates the xnor of two bitvectors.

Sets self to the xnor of self and other. Both bitvectors must be the same length. Returns true if self changed.

Panics

Panics if the bitvectors are of different length.

Examples

use bit_vec::BitVec;

let a   = 0b01100110;
let b   = 0b01010100;
let res = 0b11001101;

let mut a = BitVec::from_bytes(&[a]);
let b = BitVec::from_bytes(&[b]);

assert!(a.xnor(&b));
assert_eq!(a, BitVec::from_bytes(&[res]));

pub fn all(&self) -> bool

Returns true if all bits are 1.

Examples

use bit_vec::BitVec;

let mut bv = BitVec::from_elem(5, true);
assert_eq!(bv.all(), true);

bv.set(1, false);
assert_eq!(bv.all(), false);

pub fn iter(&self) -> Iter<'_, B>

Returns an iterator over the elements of the vector in order.

Examples

use bit_vec::BitVec;

let bv = BitVec::from_bytes(&[0b01110100, 0b10010010]);
assert_eq!(bv.iter().filter(|x| *x).count(), 7);

pub fn append(&mut self, other: &mut BitVec<B>)

Moves all bits from other into Self, leaving other empty.

Examples

use bit_vec::BitVec;

let mut a = BitVec::from_bytes(&[0b10000000]);
let mut b = BitVec::from_bytes(&[0b01100001]);

a.append(&mut b);

assert_eq!(a.len(), 16);
assert_eq!(b.len(), 0);
assert!(a.eq_vec(&[true, false, false, false, false, false, false, false,
                   false, true, true, false, false, false, false, true]));

pub fn split_off(&mut self, at: usize) -> BitVec<B>

Splits the BitVec into two at the given bit, retaining the first half in-place and returning the second one.

Panics

Panics if at is out of bounds.

Examples

use bit_vec::BitVec;
let mut a = BitVec::new();
a.push(true);
a.push(false);
a.push(false);
a.push(true);

let b = a.split_off(2);

assert_eq!(a.len(), 2);
assert_eq!(b.len(), 2);
assert!(a.eq_vec(&[true, false]));
assert!(b.eq_vec(&[false, true]));

pub fn none(&self) -> bool

Returns true if all bits are 0.

Examples

use bit_vec::BitVec;

let mut bv = BitVec::from_elem(10, false);
assert_eq!(bv.none(), true);

bv.set(3, true);
assert_eq!(bv.none(), false);

pub fn any(&self) -> bool

Returns true if any bit is 1.

Examples

use bit_vec::BitVec;

let mut bv = BitVec::from_elem(10, false);
assert_eq!(bv.any(), false);

bv.set(3, true);
assert_eq!(bv.any(), true);

pub fn to_bytes(&self) -> Vec<u8>

Organises the bits into bytes, such that the first bit in the BitVec becomes the high-order bit of the first byte. If the size of the BitVec is not a multiple of eight then trailing bits will be filled-in with false.

Examples

use bit_vec::BitVec;

let mut bv = BitVec::from_elem(3, true);
bv.set(1, false);

assert_eq!(bv.to_bytes(), [0b10100000]);

let mut bv = BitVec::from_elem(9, false);
bv.set(2, true);
bv.set(8, true);

assert_eq!(bv.to_bytes(), [0b00100000, 0b10000000]);

pub fn eq_vec(&self, v: &[bool]) -> bool

Compares a BitVec to a slice of bools. Both the BitVec and slice must have the same length.

Panics

Panics if the BitVec and slice are of different length.

Examples

use bit_vec::BitVec;

let bv = BitVec::from_bytes(&[0b10100000]);

assert!(bv.eq_vec(&[true, false, true, false,
                    false, false, false, false]));

pub fn truncate(&mut self, len: usize)

Shortens a BitVec, dropping excess elements.

If len is greater than the vector’s current length, this has no effect.

Examples

use bit_vec::BitVec;

let mut bv = BitVec::from_bytes(&[0b01001011]);
bv.truncate(2);
assert!(bv.eq_vec(&[false, true]));

pub fn reserve(&mut self, additional: usize)

Reserves capacity for at least additional more bits to be inserted in the given BitVec. The collection may reserve more space to avoid frequent reallocations.

Panics

Panics if the new capacity overflows usize.

Examples

use bit_vec::BitVec;

let mut bv = BitVec::from_elem(3, false);
bv.reserve(10);
assert_eq!(bv.len(), 3);
assert!(bv.capacity() >= 13);

pub fn reserve_exact(&mut self, additional: usize)

Reserves the minimum capacity for exactly additional more bits to be inserted in the given BitVec. Does nothing if the capacity is already sufficient.

Note that the allocator may give the collection more space than it requests. Therefore capacity can not be relied upon to be precisely minimal. Prefer reserve if future insertions are expected.

Panics

Panics if the new capacity overflows usize.

Examples

use bit_vec::BitVec;

let mut bv = BitVec::from_elem(3, false);
bv.reserve(10);
assert_eq!(bv.len(), 3);
assert!(bv.capacity() >= 13);

pub fn capacity(&self) -> usize

Returns the capacity in bits for this bit vector. Inserting any element less than this amount will not trigger a resizing.

Examples

use bit_vec::BitVec;

let mut bv = BitVec::new();
bv.reserve(10);
assert!(bv.capacity() >= 10);

pub fn grow(&mut self, n: usize, value: bool)

Grows the BitVec in-place, adding n copies of value to the BitVec.

Panics

Panics if the new len overflows a usize.

Examples

use bit_vec::BitVec;

let mut bv = BitVec::from_bytes(&[0b01001011]);
bv.grow(2, true);
assert_eq!(bv.len(), 10);
assert_eq!(bv.to_bytes(), [0b01001011, 0b11000000]);

pub fn pop(&mut self) -> Option<bool>

Removes the last bit from the BitVec, and returns it. Returns None if the BitVec is empty.

Examples

use bit_vec::BitVec;

let mut bv = BitVec::from_bytes(&[0b01001001]);
assert_eq!(bv.pop(), Some(true));
assert_eq!(bv.pop(), Some(false));
assert_eq!(bv.len(), 6);

pub fn push(&mut self, elem: bool)

Pushes a bool onto the end.

Examples

use bit_vec::BitVec;

let mut bv = BitVec::new();
bv.push(true);
bv.push(false);
assert!(bv.eq_vec(&[true, false]));

pub fn len(&self) -> usize

Returns the total number of bits in this vector

pub unsafe fn set_len(&mut self, len: usize)

Sets the number of bits that this BitVec considers initialized.

Almost certainly can cause bad stuff. Only really intended for BitSet.

pub fn is_empty(&self) -> bool

Returns true if there are no bits in this vector

pub fn clear(&mut self)

Clears all bits in this vector.

pub fn shrink_to_fit(&mut self)

Shrinks the capacity of the underlying storage as much as possible.

It will drop down as close as possible to the length but the allocator may still inform the underlying storage that there is space for a few more elements/bits.

Trait Implementations

impl Clone for BitString

fn clone(&self) -> BitString

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for BitString

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for BitString

fn default() -> BitString

Returns the “default value” for a type.

impl Deref for BitString

type Target = BitVec

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl DerefMut for BitString

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<'de> Deserialize<'de> for BitString

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl From<BitVec> for BitString

fn from(bit_vec: BitVec) -> Self

Converts to this type from the input type.

impl PartialEq for BitString

fn eq(&self, other: &BitString) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for BitString

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for BitString