perldoc > Bit::Vector

man perldoc info pydoc3 ri search

📛 NAME

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

🚀 Quick Reference

Use Case	Command	Description
Create a bit vector	Bit::Vector->new($bits)	Create a new bit vector of given size, all bits cleared
Set a bit	$vector->Bit_On($index)	Set a specific bit to 1
Test a bit	$vector->bit_test($index)	Check if a bit is set (returns 0 or 1)
Convert to hex string	$vector->to_Hex()	Export as hexadecimal string
Add two numbers	$vec3->add($vec1,$vec2,$carry)	Add two bit vectors with carry
Set operations (union)	$vec3->Or($vec1,$vec2)	Compute bitwise OR (union)

📋 SYNOPSIS

🔗 OVERLOADED OPERATORS

See Bit::Vector::Overload(3).

🔗 MORE STRING IMPORT/EXPORT

See Bit::Vector::String(3).

📦 CLASS METHODS

• Version – $version = Bit::Vector->Version();
• Word_Bits – $bits = Bit::Vector->Word_Bits(); (bits in a machine word)
• Long_Bits – $bits = Bit::Vector->Long_Bits(); (bits in an unsigned long)
• new – $vector = Bit::Vector->new($bits); (constructor)
• new (multi) – @veclist = Bit::Vector->new($bits,$count);
• new_Hex – $vector = Bit::Vector->new_Hex($bits,$string);
• new_Bin – $vector = Bit::Vector->new_Bin($bits,$string);
• new_Dec – $vector = Bit::Vector->new_Dec($bits,$string);
• new_Enum – $vector = Bit::Vector->new_Enum($bits,$string);
• Concat_List – $vector = Bit::Vector->Concat_List(@vectors);

🛠️ OBJECT METHODS

• new – $vec2 = $vec1->new($bits); (alternative call)
• Shadow – $vec2 = $vec1->Shadow(); (new vector, same size but empty)
• Clone – $vec2 = $vec1->Clone(); (exact duplicate)
• Concat – $vector = $vec1->Concat($vec2);
• Concat_List – $vector = $vec1->Concat_List($vec2,$vec3,...);
• Size – $bits = $vector->Size();
• Resize – $vector->Resize($bits);
• Copy – $vec2->Copy($vec1);
• Empty – $vector->Empty();
• Fill – $vector->Fill();
• Flip – $vector->Flip();
• Primes – $vector->Primes(); (Sieve of Eratosthenes)
• Reverse – $vec2->Reverse($vec1);
• Interval_Empty – $vector->Interval_Empty($min,$max);
• Interval_Fill – $vector->Interval_Fill($min,$max);
• Interval_Flip – $vector->Interval_Flip($min,$max);
• Interval_Reverse – $vector->Interval_Reverse($min,$max);
• Interval_Scan_inc – if (($min,$max) = $vector->Interval_Scan_inc($start))
• Interval_Scan_dec – if (($min,$max) = $vector->Interval_Scan_dec($start))
• Interval_Copy – $vec2->Interval_Copy($vec1,$offset2,$offset1,$length);
• Interval_Substitute – $vec2->Interval_Substitute($vec1,$off2,$len2,$off1,$len1);
• is_empty – if ($vector->is_empty())
• is_full – if ($vector->is_full())
• equal – if ($vec1->equal($vec2))
• Lexicompare (unsigned) – if ($vec1->Lexicompare($vec2) == 0) etc.
• Compare (signed) – if ($vec1->Compare($vec2) == 0) etc.
• to_Hex – $string = $vector->to_Hex();
• from_Hex – $vector->from_Hex($string);
• to_Bin – $string = $vector->to_Bin();
• from_Bin – $vector->from_Bin($string);
• to_Dec – $string = $vector->to_Dec();
• from_Dec – $vector->from_Dec($string);
• to_Enum – $string = $vector->to_Enum(); (e.g. "2,3,5-7,11,13-19")
• from_Enum – $vector->from_Enum($string);
• Bit_Off – $vector->Bit_Off($index);
• Bit_On – $vector->Bit_On($index);
• bit_flip – $bit = $vector->bit_flip($index);
• bit_test / contains – $bit = $vector->bit_test($index);
• Bit_Copy – $vector->Bit_Copy($index,$bit);
• LSB – $vector->LSB($bit);
• MSB – $vector->MSB($bit);
• lsb – $bit = $vector->lsb();
• msb – $bit = $vector->msb();
• rotate_left – $carry = $vector->rotate_left();
• rotate_right – $carry = $vector->rotate_right();
• shift_left – $carry = $vector->shift_left($carry);
• shift_right – $carry = $vector->shift_right($carry);
• Move_Left – $vector->Move_Left($bits);
• Move_Right – $vector->Move_Right($bits);
• Insert – $vector->Insert($offset,$bits);
• Delete – $vector->Delete($offset,$bits);
• increment – $carry = $vector->increment();
• decrement – $carry = $vector->decrement();
• inc – $overflow = $vec2->inc($vec1);
• dec – $overflow = $vec2->dec($vec1);
• add – $carry = $vec3->add($vec1,$vec2,$carry);
• subtract – $carry = $vec3->subtract($vec1,$vec2,$carry);
• Neg / Negate – $vec2->Neg($vec1);
• Abs / Absolute – $vec2->Abs($vec1);
• Sign – if ($vector->Sign() == 0)
• Multiply – $vec3->Multiply($vec1,$vec2);
• Divide – $quot->Divide($vec1,$vec2,$rest);
• GCD – $vecgcd->GCD($veca,$vecb);
• Power – $vec3->Power($vec1,$vec2);
• Block_Store – $vector->Block_Store($buffer);
• Block_Read – $buffer = $vector->Block_Read();
• Word_Size – $size = $vector->Word_Size();
• Word_Store – $vector->Word_Store($offset,$word);
• Word_Read – $word = $vector->Word_Read($offset);
• Word_List_Store – $vector->Word_List_Store(@words);
• Word_List_Read – @words = $vector->Word_List_Read();
• Word_Insert – $vector->Word_Insert($offset,$count);
• Word_Delete – $vector->Word_Delete($offset,$count);
• Chunk_Store – $vector->Chunk_Store($chunksize,$offset,$chunk);
• Chunk_Read – $chunk = $vector->Chunk_Read($chunksize,$offset);
• Chunk_List_Store – $vector->Chunk_List_Store($chunksize,@chunks);
• Chunk_List_Read – @chunks = $vector->Chunk_List_Read($chunksize);
• Index_List_Remove – $vector->Index_List_Remove(@indices);
• Index_List_Store – $vector->Index_List_Store(@indices);
• Index_List_Read – @indices = $vector->Index_List_Read();
• Or / Union – $vec3->Or($vec1,$vec2);
• And / Intersection – $vec3->And($vec1,$vec2);
• AndNot / Difference – $vec3->AndNot($vec1,$vec2);
• Xor / ExclusiveOr – $vec3->Xor($vec1,$vec2);
• Not / Complement – $vec2->Not($vec1);
• subset – if ($set1->subset($set2))
• Norm – $norm = $set->Norm();
• Min – $min = $set->Min();
• Max – $max = $set->Max();
• Multiplication – $matrix3->Multiplication(...);
• Product – $matrix3->Product(...);
• Closure – $matrix->Closure($rows,$cols);
• Transpose – $matrix2->Transpose(...);

⚠️ IMPORTANT NOTES

• Method naming conventions: Method names completely in lower case indicate a boolean return value (except new()).
• Boolean values: Always numeric zero (0) for false, one (1) for true.
• Negative numbers: All numeric input parameters are treated as UNSIGNED; negative numbers are interpreted as large positive numbers due to two's complement.
• Bit order: Bit vectors are stored least order bit and least order word first internally. Block_Read()/Block_Store() use "least order byte first" order for portability.
• "Word" related methods: Methods beginning with Word_ are MACHINE-DEPENDENT. Use Chunk_ methods for portability (chunk sizes up to 32 bits).
• Chunk sizes: Legal chunk sizes range from 1 to Bit::Vector->Long_Bits() bits. For portability, use ≤ 32 bits.
• Matching sizes: Most methods require all bit vector arguments to have identical sizes. Exceptions: Concat(), Concat_List(), Copy(), Interval_Copy(), Interval_Substitute(), Multiply(), Power().
• Index ranges: All indices must be between 0 and $vector->Size()-1.
• Object persistence: Since version 6.5, Bit::Vector objects can be serialized with Storable automatically. See Storable(3).

📖 DESCRIPTION

🔗 OVERLOADED OPERATORS

See Bit::Vector::Overload(3).

🔗 MORE STRING IMPORT/EXPORT

See Bit::Vector::String(3).

📦 CLASS METHODS

• $version = Bit::Vector->Version(); – Returns the current version number.
• $bits = Bit::Vector->Word_Bits(); – Returns the number of bits in an unsigned int (machine word).
• $bits = Bit::Vector->Long_Bits(); – Returns the number of bits in an unsigned long.
• $vector = Bit::Vector->new($bits); – Constructor. Creates a bit vector of size $bits (all bits cleared). Exception if memory allocation fails. Negative $bits interpreted as large positive.
• @veclist = Bit::Vector->new($bits,$count); – Creates multiple bit vectors at once. Returns a list of $count vectors.
• $vector = Bit::Vector->new_Hex($bits,$string); – Alternative constructor: creates and initializes from hex string.
• $vector = Bit::Vector->new_Bin($bits,$string); – Alternative constructor: creates and initializes from binary string.
• $vector = Bit::Vector->new_Dec($bits,$string); – Alternative constructor: creates and initializes from decimal string.
• $vector = Bit::Vector->new_Enum($bits,$string); – Alternative constructor: creates and initializes from enumeration string.
• $vector = Bit::Vector->Concat_List(@vectors); – Creates a new vector by concatenating all given vectors. Rightmost vector becomes least significant.

🛠️ OBJECT METHODS

• $vec2 = $vec1->new($bits); – Alternative way to call constructor (using an existing vector as anchor).
• $vec2 = $vec1->Shadow(); – Creates a new empty vector of same size as $vec1.
• $vec2 = $vec1->Clone(); – Creates an exact copy of $vec1.
• $vector = $vec1->Concat($vec2); – Returns concatenation of $vec1 (most significant) and $vec2 (least significant).
• $vector = $vec1->Concat_List($vec2,$vec3,...); – Concatenates multiple vectors.
• $bits = $vector->Size(); – Returns the size (number of bits) of the vector.
• $vector->Resize($bits); – Changes the size of the vector, preserving as many bits as fit. May allocate new memory if needed.
• $vec2->Copy($vec1); – Copies contents of $vec1 to $vec2. If source is larger, truncates; if target is larger, sign-extends.
• $vector->Empty(); – Clears all bits.
• $vector->Fill(); – Sets all bits.
• $vector->Flip(); – Flips (complements) all bits.
• $vector->Primes(); – Sets all bits whose indices are prime numbers (Sieve of Eratosthenes).
• $vec2->Reverse($vec1); – Reverses order of bits (LSB ↔ MSB).
• $vector->Interval_Empty($min,$max); – Clears bits in interval [$min, $max].
• $vector->Interval_Fill($min,$max); – Sets bits in interval.
• $vector->Interval_Flip($min,$max); – Flips bits in interval.
• $vector->Interval_Reverse($min,$max); – Reverses order of bits in interval.
• if (($min,$max) = $vector->Interval_Scan_inc($start)) – Finds next contiguous block of set bits scanning upward from $start. Returns empty list if none.
• if (($min,$max) = $vector->Interval_Scan_dec($start)) – Same, scanning downward.
• $vec2->Interval_Copy($vec1,$offset2,$offset1,$length); – Copies a stretch of bits from $vec1 to $vec2. Handles overlapping.
• $vec2->Interval_Substitute($vec1,$off2,$len2,$off1,$len1); – Replaces a stretch in $vec2 with a stretch from $vec1. Automatically resizes target vector. Similar to splice.
• if ($vector->is_empty()) – Returns true if all bits are cleared (zero).
• if ($vector->is_full()) – Returns true if all bits are set (minus one).
• if ($vec1->equal($vec2)) – Returns true if vectors are identical.
• $cmp = $vec1->Lexicompare($vec2); – Compares as unsigned numbers: returns -1, 0, or 1.
• $cmp = $vec1->Compare($vec2); – Compares as signed numbers (two's complement).
• $string = $vector->to_Hex(); – Returns hexadecimal string (LSB at right).
• $vector->from_Hex($string); – Reads from hex string. Ignores extra digits; clears remaining bits.
• $string = $vector->to_Bin(); – Returns binary string (LSB at right).
• $vector->from_Bin($string); – Reads from binary string.
• $string = $vector->to_Dec(); – Converts to decimal string (signed). Slow; use sparingly.
• $vector->from_Dec($string); – Converts decimal string to bit vector. Supports negative numbers. Throws overflow error if too large.
• $string = $vector->to_Enum(); – Returns enumeration of set bits (e.g., "2,3,5-7").
• $vector->from_Enum($string); – Sets bits from enumeration string.
• $vector->Bit_Off($index); – Clears a single bit.
• $vector->Bit_On($index); – Sets a single bit.
• $bit = $vector->bit_flip($index); – Flips a bit and returns new state.
• $bit = $vector->bit_test($index); – Returns state of a bit (0 or 1).
• $vector->Bit_Copy($index,$bit); – Sets a bit to given boolean value.
• $vector->LSB($bit); – Sets the least significant bit.
• $vector->MSB($bit); – Sets the most significant bit.
• $bit = $vector->lsb(); – Returns least significant bit.
• $bit = $vector->msb(); – Returns most significant bit.
• $carry = $vector->rotate_left(); – Rotates left, returns carry out.
• $carry = $vector->rotate_right(); – Rotates right.
• $carry = $vector->shift_left($carry_in); – Shifts left, shifting in $carry_in.
• $carry = $vector->shift_right($carry_in); – Shifts right.
• $vector->Move_Left($bits); – Moves (shifts) left by $bits positions, losing upper bits.
• $vector->Move_Right($bits); – Moves right by $bits positions, losing lower bits.
• $vector->Insert($offset,$bits); – Inserts $bits zero bits at $offset, shifting up, losing upper bits.
• $vector->Delete($offset,$bits); – Deletes $bits bits at $offset, shifting down, clearing upper bits.
• $carry = $vector->increment(); – Increments as unsigned. Returns carry if overflow.
• $carry = $vector->decrement(); – Decrements as unsigned.
• $overflow = $vec2->inc($vec1); – Copies and increments, returns overflow flag.
• $overflow = $vec2->dec($vec1); – Copies and decrements.
• $carry = $vec3->add($vec1,$vec2,$carry); – Adds with carry. In list context returns (carry, overflow).
• $carry = $vec3->subtract($vec1,$vec2,$carry); – Subtracts with carry.
• $vec2->Neg($vec1); – Two's complement (negate).
• $vec2->Abs($vec1); – Absolute value.
• $sign = $vector->Sign(); – Returns 0 (zero), 1 (positive), or -1 (negative).
• $vec3->Multiply($vec1,$vec2); – Signed multiplication. Result may be larger; overflow if too small.
• $quot->Divide($vec1,$vec2,$rest); – Signed division. Returns quotient and remainder.
• $vecgcd->GCD($veca,$vecb); – Greatest common divisor (Euclid's algorithm).
• $vecgcd->GCD($vecx,$vecy,$veca,$vecb); – Extended GCD: also returns coefficients x and y such that GCD = x*a + y*b.
• $vec3->Power($vec1,$vec2); – Exponentiation (base^exponent). Efficient divide-and-conquer.
• $vector->Block_Store($buffer); – Loads bit vector from a binary string (low-order byte first).
• $buffer = $vector->Block_Read(); – Exports bit vector as binary string.
• $size = $vector->Word_Size(); – Returns number of machine words in the internal representation.
• $vector->Word_Store($offset,$word); – Stores a machine word at given offset.
• $word = $vector->Word_Read($offset); – Reads a machine word.
• $vector->Word_List_Store(@words); – Stores list of words (least significant first).
• @words = $vector->Word_List_Read(); – Returns list of words.
• $vector->Word_Insert($offset,$count); – Inserts words at offset.
• $vector->Word_Delete($offset,$count); – Deletes words.
• $vector->Chunk_Store($chunksize,$offset,$chunk); – Stores a chunk of bits (up to Long_Bits).
• $chunk = $vector->Chunk_Read($chunksize,$offset); – Reads a chunk of bits.
• $vector->Chunk_List_Store($chunksize,@chunks); – Fills vector with list of chunks.
• @chunks = $vector->Chunk_List_Read($chunksize); – Returns list of chunks. Caution: can be huge.
• $vector->Index_List_Remove(@indices); – Clears specified bits.
• $vector->Index_List_Store(@indices); – Sets specified bits.
• @indices = $vector->Index_List_Read(); – Returns list of indices of set bits.
• $vec3->Or($vec1,$vec2); – Bitwise OR (union of sets).
• $vec3->And($vec1,$vec2); – Bitwise AND (intersection).
• $vec3->AndNot($vec1,$vec2); – Bitwise AND NOT (set difference).
• $vec3->Xor($vec1,$vec2); – Bitwise XOR (symmetric difference).
• $vec2->Not($vec1); – Bitwise NOT (complement).
• if ($set1->subset($set2)) – Returns true if $set1 is subset of $set2.
• $norm = $set->Norm(); – Returns number of set bits (norm).
• $norm = $set->Norm2(); – Alternative norm calculation (may be faster for sparse sets).
• $norm = $set->Norm3(); – Another norm method (slowest on average).
• $min = $set->Min(); – Returns minimum index of set bit, or MAX_LONG if empty.
• $max = $set->Max(); – Returns maximum index of set bit, or MIN_LONG if empty.
• $m3->Multiplication($r3,$c3,$m1,$r1,$c1,$m2,$r2,$c2); – Boolean matrix multiplication (XOR addition).
• $m3->Product($r3,$c3,$m1,$r1,$c1,$m2,$r2,$c2); – Boolean matrix multiplication (OR addition).
• $matrix->Closure($rows,$cols); – Reflexive transitive closure using Kleene's algorithm.
• $matrix2->Transpose($rows2,$cols2,$matrix1,$rows1,$cols1); – Matrix transpose.

👀 SEE ALSO

Bit::Vector::Overload(3), Bit::Vector::String(3), Storable(3).

Set::IntRange(3), Math::MatrixBool(3), Math::MatrixReal(3), DFA::Kleene(3), Math::Kleene(3), Graph::Kruskal(3).

🏷️ VERSION

This man page documents "Bit::Vector" version 7.4.

✍️ AUTHOR

Steffen Beyer
mailto:STBEY AT cpan.org
http://www.engelschall.com/u/sb/download/

©️ COPYRIGHT

Copyright (c) 1995 - 2013 by Steffen Beyer. All rights reserved.

📜 LICENSE

This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself, i.e., under the terms of the "Artistic License" or the "GNU General Public License".

The C library at the core of this Perl module can additionally be redistributed and/or modified under the terms of the "GNU Library General Public License".

Please refer to the files "Artistic.txt", "GNU_GPL.txt" and "GNU_LGPL.txt" in this distribution for details!

⚖️ DISCLAIMER

This package is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

See the "GNU General Public License" for more details.

📛 NAME 🚀 Quick Reference 📋 SYNOPSIS ⚠️ IMPORTANT NOTES 📖 DESCRIPTION 👀 SEE ALSO 🏷️ VERSION ✍️ AUTHOR ©️ COPYRIGHT 📜 LICENSE ⚖️ DISCLAIMER