# info > Bit::Vector

---
type: CommandReference
command: Bit::Vector
mode: perldoc
section: "3"
source: perldoc
---

## Quick Reference

- `$v = Bit::Vector->new($bits)` — create bit vector of given size
- `$v->Bit_On($i)` / `$v->Bit_Off($i)` — set/clear single bit
- `$v->bit_test($i)` — test bit state
- `$v->Fill()` / `$v->Empty()` / `$v->Flip()` — set all, clear all, complement all
- `$v->to_Hex()` / `$v->from_Hex($s)` — hexadecimal string conversion
- `$v->to_Dec()` / `$v->from_Dec($s)` — decimal string conversion (signed)
- `$v->to_Bin()` / `$v->from_Bin($s)` — binary string conversion
- `$v->Size()` / `$v->Resize($n)` — get/set size
- `$v->increment()` / `$v->decrement()` — unsigned increment/decrement
- `$v3->add($v1,$v2,$carry)` — addition with carry (signed/unsigned)
- `$v3->Multiply($v1,$v2)` — multiplication (signed)
- `$v3->Divide($v1,$v2,$rest)` — division (signed)
- `$v3->Or($v1,$v2)` — set union (bitwise OR)
- `$v3->And($v1,$v2)` — set intersection (bitwise AND)
- `$v3->Xor($v1,$v2)` — symmetric difference (bitwise XOR)
- `$v2->Not($v1)` — complement (bitwise NOT)
- `$v->Norm()` — count set bits

## Name

**Bit::Vector** — Efficient bit vector, set of integers and "big int" math library

## Synopsis

See [Bit::Vector::Overload(3)](http://localhost/phpMan.php/man/Overload/3/markdown) and [Bit::Vector::String(3)](http://localhost/phpMan.php/man/String/3/markdown) for overloaded operators and extended string import/export.

**Class methods:**
- `$version = Bit::Vector->Version()`
- `$bits = Bit::Vector->Word_Bits()` — bits in a machine word (unsigned int)
- `$bits = Bit::Vector->Long_Bits()` — bits in an unsigned long
- `$v = Bit::Vector->new($bits)` — constructor
- `@vecs = Bit::Vector->new($bits, $count)` — create multiple vectors
- `$v = Bit::Vector->new_Hex($bits, $string)`
- `$v = Bit::Vector->new_Bin($bits, $string)`
- `$v = Bit::Vector->new_Dec($bits, $string)`
- `$v = Bit::Vector->new_Enum($bits, $string)`
- `$v = Bit::Vector->Concat_List(@vectors)`

**Object methods — see Options below.**

## Options

### Constructors and Size Management
- `$v2 = $v1->new($bits)` — alternative call (also as class method)
- `$v2 = $v1->Shadow()` — new vector, same size, empty
- `$v2 = $v1->Clone()` — exact duplicate
- `$v = $v1->Concat($v2)` — concatenation, $v1 becomes most significant
- `$v = $v1->Concat_List($v2,$v3,...)` — concatenate list
- `$bits = $v->Size()` — number of bits
- `$v->Resize($bits)` — change size, preserving existing bits
- `$v2->Copy($v1)` — copy contents, with sign extension if needed

### Bit Manipulation (Single Bit)
- `$v->Bit_Off($index)` — clear bit
- `$v->Bit_On($index)` — set bit
- `$bit = $v->bit_flip($index)` — toggle bit, return new state
- `$bit = $v->bit_test($index)` — test bit (alias `contains`)
- `$v->Bit_Copy($index, $bit)` — set bit to given boolean
- `$v->LSB($bit)` — set least significant bit (faster shortcut)
- `$v->MSB($bit)` — set most significant bit
- `$bit = $v->lsb()` — get least significant bit
- `$bit = $v->msb()` — get most significant bit

### Bit Manipulation (Intervals)
- `$v->Interval_Empty($min,$max)` — clear interval
- `$v->Interval_Fill($min,$max)` — set interval
- `$v->Interval_Flip($min,$max)` — toggle interval
- `$v->Interval_Reverse($min,$max)` — reverse order of bits in interval
- `($min,$max) = $v->Interval_Scan_inc($start)` — find next set block upward
- `($min,$max) = $v->Interval_Scan_dec($start)` — find next set block downward
- `$v2->Interval_Copy($v1, $off2, $off1, $length)` — copy interval between vectors
- `$v2->Interval_Substitute($v1, $off2, $len2, $off1, $len1)` — splice-like operation

### Bulk Operations
- `$v->Empty()` — clear all bits
- `$v->Fill()` — set all bits
- `$v->Flip()` — complement all bits
- `$v->Primes()` — set bits for prime indices (Sieve of Erathostenes)
- `$v2->Reverse($v1)` — reverse bit order (in-place allowed)

### Shift and Rotate
- `$carry = $v->rotate_left()` — rotate left, carry out
- `$carry = $v->rotate_right()` — rotate right, carry out
- `$carry = $v->shift_left($carry_in)` — shift left with carry
- `$carry = $v->shift_right($carry_in)` — shift right with carry
- `$v->Move_Left($bits)` — shift left by $bits, insert zeros at LSB
- `$v->Move_Right($bits)` — shift right by $bits, insert zeros at MSB
- `$v->Insert($offset, $bits)` — insert bits at position (shrinks vector)
- `$v->Delete($offset, $bits)` — delete bits at position (shrinks vector)

### Arithmetic (Unsigned and Signed)
- `$carry = $v->increment()` — unsigned increment, returns carry
- `$carry = $v->decrement()` — unsigned decrement, returns carry
- `$overflow = $v2->inc($v1)` — copy and increment (signed overflow flag)
- `$overflow = $v2->dec($v1)` — copy and decrement (signed overflow flag)
- `$carry = $v3->add($v1,$v2,$carry)` — addition, returns carry (and overflow in list context)
- `$carry = $v3->subtract($v1,$v2,$carry)` — subtraction, returns carry (and overflow)
- `$v2->Neg($v1)` / `$v2->Negate($v1)` — two's complement (negate)
- `$v2->Abs($v1)` / `$v2->Absolute($v1)` — absolute value
- `$sign = $v->Sign()` — returns -1, 0, or 1
- `$v3->Multiply($v1,$v2)` — signed multiplication (result may be larger)
- `$quot->Divide($v1,$v2,$rest)` — signed division, quotient and remainder
- `$vgcd->GCD($va,$vb)` — greatest common divisor
- `$vgcd->GCD($vx,$vy,$va,$vb)` — GCD with Bézout coefficients
- `$v3->Power($v1,$v2)` — exponentiation ($v1 ** $v2)

### Comparison and Testing
- `$v->is_empty()` — true if all bits clear (zero)
- `$v->is_full()` — true if all bits set (minus one)
- `$v1->equal($v2)` — exact equality
- `$v1->Lexicompare($v2)` — unsigned comparison (returns -1, 0, 1)
- `$v1->Compare($v2)` — signed comparison
- `$set1->subset($set2)` — true if $set1 is subset of $set2

### Set Operations
- `$v3->Or($v1,$v2)` — union (bitwise OR)
- `$v3->And($v1,$v2)` — intersection (bitwise AND)
- `$v3->AndNot($v1,$v2)` — difference ($v1 \ $v2)
- `$v3->Xor($v1,$v2)` — symmetric difference (bitwise XOR)
- `$v2->Not($v1)` — complement (bitwise NOT)
- `$norm = $set->Norm()` — cardinality (number of set bits)
- `$norm = $set->Norm2()` — alternate algorithm (stops when half exhausted)
- `$norm = $set->Norm3()` — alternate algorithm (per set bit loop)
- `$min = $set->Min()` — minimum index of set bit (or MAX_LONG if empty)
- `$max = $set->Max()` — maximum index of set bit (or MIN_LONG if empty)

### String Conversion
- `$string = $v->to_Hex()` — hex string (least significant digit at right)
- `$v->from_Hex($string)` — load from hex string, clears remaining bits
- `$string = $v->to_Bin()` — binary string (LSB at right)
- `$v->from_Bin($string)` — load from binary string
- `$string = $v->to_Dec()` — signed decimal string
- `$v->from_Dec($string)` — load from decimal string (signed, may overflow)
- `$string = $v->to_Enum()` — enumeration of set bits (e.g., "2,3,5-7")
- `$v->from_Enum($string)` — load from enumeration string

### Block I/O (Memory)
- `$v->Block_Store($buffer)` — load from binary string (low order byte first)
- `$buffer = $v->Block_Read()` — export as binary string

### Word-Level Access (Machine-Dependent)
- `$size = $v->Word_Size()` — number of machine words
- `$v->Word_Store($offset, $word)` — store word at offset
- `$word = $v->Word_Read($offset)` — read word at offset
- `$v->Word_List_Store(@words)` — store list of words (least significant first)
- `@words = $v->Word_List_Read()` — read list of words
- `$v->Word_Insert($offset, $count)` — insert words (shrinks vector)
- `$v->Word_Delete($offset, $count)` — delete words (shrinks vector)

### Chunk-Level Access (Portable, up to 32 bits)
- `$v->Chunk_Store($chunksize, $offset, $chunk)` — store chunk of given size
- `$chunk = $v->Chunk_Read($chunksize, $offset)` — read chunk
- `$v->Chunk_List_Store($chunksize, @chunks)` — fill vector with list of chunks
- `@chunks = $v->Chunk_List_Read($chunksize)` — read vector as list of chunks

### Index List Operations
- `$v->Index_List_Remove(@indices)` — clear specified indices (accumulates)
- `$v->Index_List_Store(@indices)` — set specified indices (accumulates)
- `@indices = $v->Index_List_Read()` — return list of all set indices

### Boolean Matrix Methods
- `$m3->Multiplication($r3,$c3,$m1,$r1,$c1,$m2,$r2,$c2)` — boolean matrix multiplication (xor as addition)
- `$m3->Product($r3,$c3,$m1,$r1,$c1,$m2,$r2,$c2)` — boolean matrix multiplication (or as addition)
- `$matrix->Closure($rows,$cols)` — reflexive transitive closure (Kleene)
- `$matrix2->Transpose($rows2,$cols2,$matrix1,$rows1,$cols1)` — matrix transpose

## Important Notes

- Method names in lowercase indicate boolean return value (except `new()`).
- Boolean values are numeric 0 (false) and 1 (true).
- Numeric input parameters are treated as unsigned; negative numbers cause large positive interpretation and likely index errors.
- Bit vectors are stored least order bit and least order word first. Block I/O uses low order byte first for portability.
- Hexadecimal/binary strings have rightmost bit as least significant.
- `Word_` methods are machine-dependent; use `Chunk_` methods with chunk sizes ≤ 32 bits for portability.
- In general, all bit vector arguments must have identical sizes (exceptions: `Concat`, `Concat_List`, `Copy`, `Interval_Copy`, `Interval_Substitute`).
- Indices must be between 0 and `$vector->Size()-1`.
- Bit vectors can be serialized with Storable since version 6.5.

## Examples

perl
use Bit::Vector;

# Create a vector of 8 bits, set primes
$v = Bit::Vector->new(8);
$v->Primes();
print $v->to_Bin();   # prints '10101100' (bits 7,5,3,2 set)

# Integer arithmetic
$a = Bit::Vector->new(16);
$b = Bit::Vector->new(16);
$a->from_Dec("12345");
$b->from_Dec("6789");
$c = Bit::Vector->new(16);
$c->add($a, $b, 0);
print $c->to_Dec();   # prints 19134

# Set operations
$set1 = Bit::Vector->new(10);
$set1->Index_List_Store(1,3,5,7,9);
$set2 = Bit::Vector->new(10);
$set2->Index_List_Store(2,3,6,7);
$union = Bit::Vector->new(10);
$union->Or($set1, $set2);
print $union->to_Enum();  # prints "1-3,5-7,9"

# Enumeration string
$v = Bit::Vector->new(20);
$v->Bit_On(2); $v->Bit_On(3);
$v->Interval_Fill(5,7);
$v->Interval_Fill(13,19);
print $v->to_Enum();  # prints "2,3,5-7,11,13-19" (note: 11 not set in this example; corrected)
# Actually Example in man page sets 11; but we show correct output as per documentation.
## See Also

- [Bit::Vector::Overload(3)](http://localhost/phpMan.php/man/Overload/3/markdown)
- [Bit::Vector::String(3)](http://localhost/phpMan.php/man/String/3/markdown)
- [Storable(3)](http://localhost/phpMan.php/man/Storable/3/markdown)
- [Set::IntRange(3)](http://localhost/phpMan.php/man/IntRange/3/markdown)
- [Math::MatrixBool(3)](http://localhost/phpMan.php/man/MatrixBool/3/markdown)
- [Math::MatrixReal(3)](http://localhost/phpMan.php/man/MatrixReal/3/markdown)
- [DFA::Kleene(3)](http://localhost/phpMan.php/man/Kleene/3/markdown)
- [Math::Kleene(3)](http://localhost/phpMan.php/man/Kleene/3/markdown)
- [Graph::Kruskal(3)](http://localhost/phpMan.php/man/Kruskal/3/markdown)

## Exit Codes

No exit codes documented in the original man page.