info > Bit::Vector::Overload

man perldoc info pydoc3 ri search

📖 NAME

Bit::Vector::Overload – Overloaded operators add-on for Bit::Vector

🚀 Quick Reference

Use Case	Command	Description
🔧 Configuration	Bit::Vector->Configuration("in=hex,ops=arithmetic,out=bin")	Set scalar input format, operator semantics, and string output format
🔤 String conversion	"$vector"	Convert bit vector to string (format depends on configuration)
✅ Emptiness check	if ($vector)	True if any bit is set
🔁 Complement	~$vector	One's complement (invert all bits)
➖ Negation	-$vector	Two's complement (negate)
📏 Norm	abs($vector)	Number of set bits (default) or absolute value
🔗 Concatenation	$v1 . $v2	Concatenate two bit vectors
🔁 Duplication	$v1 x $factor	Repeat bit vector n times
⬅️ Shift left	$v1 > $bits	Shift right, zero fill
🔀 Union (set)	$v1 | $v2	Bitwise OR (set union)
🔀 Union (set, alt)	$v1 + $v2 (set config)	Same as | (default)
🔀 Intersection	$v1 & $v2	Bitwise AND (set intersection)
🔀 Intersection (alt)	$v1 * $v2 (set config)	Same as & (default)
🔀 Exclusive OR	$v1 ^ $v2	Bitwise XOR (symmetric difference)
🔀 Set difference	$v1 - $v2 (set config)	Set difference
➕ Addition (arithmetic)	$v1 + $v2 (arithmetic config)	Arithmetic addition
➖ Subtraction (arithmetic)	$v1 - $v2 (arithmetic config)	Arithmetic subtraction
✖️ Multiplication	$v1 * $v2 (arithmetic config)	Arithmetic multiplication
➗ Division	$v1 / $v2	Arithmetic division
🔢 Modulo	$v1 % $v2	Arithmetic remainder
🔢 Exponentiation	$v1 ** $v2	Arithmetic power
➕ Increment	++$vector	Pre/post increment
➖ Decrement	--$vector	Pre/post decrement
⚖️ Comparison (unsigned)	$v1 cmp $v2	Lexical comparison (unsigned)
⚖️ Comparison (signed)	$v1 $v2	Numeric comparison (signed)
🔗 Equality	$v1 == $v2 or eq	Test equality
🔗 Subset	$v1 = $v2 (set config)	Superset relationship
🔗 True superset	$v1 > $v2 (set config)	True superset

📋 USAGE

Note that you do not need to use Bit::Vector; in addition to this module. Simply use Bit::Vector::Overload; instead of use Bit::Vector;. You can still use all the methods from the Bit::Vector module in addition to the overloaded operators provided here.

📝 SYNOPSIS

Configuration
    $config = Bit::Vector->Configuration();
    Bit::Vector->Configuration($config);
    $oldconfig = Bit::Vector->Configuration($newconfig);

String Conversion
    $string = "$vector";             #  depending on configuration
    print "\$vector = '$vector'\n";

Emptyness
    if ($vector)  #  if not empty (non-zero)
    if (! $vector)  #  if empty (zero)
    unless ($vector)  #  if empty (zero)

Complement (one's complement)
    $vector2 = ~$vector1;
    $vector = ~$vector;

Negation (two's complement)
    $vector2 = -$vector1;
    $vector = -$vector;

Norm
    $norm = abs($vector);  #  depending on configuration

Absolute
    $vector2 = abs($vector1);  #  depending on configuration

Concatenation
    $vector3 = $vector1 . $vector2;
    $vector1 .= $vector2;
    $vector1 = $vector2 . $vector1;
    $vector2 = $vector1 . $scalar;  #  depending on configuration
    $vector2 = $scalar . $vector1;
    $vector .= $scalar;

Duplication
    $vector2 = $vector1 x $factor;
    $vector x= $factor;

Shift Left
    $vector2 = $vector1 >= $bits;

Union
    $vector3 = $vector1 | $vector2;
    $vector1 |= $vector2;
    $vector2 = $vector1 | $scalar;
    $vector |= $scalar;

    $vector3 = $vector1 + $vector2;  #  depending on configuration
    $vector1 += $vector2;
    $vector2 = $vector1 + $scalar;
    $vector += $scalar;

Intersection
    $vector3 = $vector1 & $vector2;
    $vector1 &= $vector2;
    $vector2 = $vector1 & $scalar;
    $vector &= $scalar;

    $vector3 = $vector1 * $vector2;  #  depending on configuration
    $vector1 *= $vector2;
    $vector2 = $vector1 * $scalar;
    $vector *= $scalar;

ExclusiveOr
    $vector3 = $vector1 ^ $vector2;
    $vector1 ^= $vector2;
    $vector2 = $vector1 ^ $scalar;
    $vector ^= $scalar;

Set Difference
    $vector3 = $vector1 - $vector2;  #  depending on configuration
    $vector1 -= $vector2;
    $vector1 = $vector2 - $vector1;
    $vector2 = $vector1 - $scalar;
    $vector2 = $scalar - $vector1;
    $vector -= $scalar;

Addition
    $vector3 = $vector1 + $vector2;  #  depending on configuration
    $vector1 += $vector2;
    $vector2 = $vector1 + $scalar;
    $vector += $scalar;

Subtraction
    $vector3 = $vector1 - $vector2;  #  depending on configuration
    $vector1 -= $vector2;
    $vector1 = $vector2 - $vector1;
    $vector2 = $vector1 - $scalar;
    $vector2 = $scalar - $vector1;
    $vector -= $scalar;

Multiplication
    $vector3 = $vector1 * $vector2;  #  depending on configuration
    $vector1 *= $vector2;
    $vector2 = $vector1 * $scalar;
    $vector *= $scalar;

Division
    $vector3 = $vector1 / $vector2;
    $vector1 /= $vector2;
    $vector1 = $vector2 / $vector1;
    $vector2 = $vector1 / $scalar;
    $vector2 = $scalar / $vector1;
    $vector /= $scalar;

Modulo
    $vector3 = $vector1 % $vector2;
    $vector1 %= $vector2;
    $vector1 = $vector2 % $vector1;
    $vector2 = $vector1 % $scalar;
    $vector2 = $scalar % $vector1;
    $vector %= $scalar;

Exponentiation
    $vector3 = $vector1 ** $vector2;
    $vector1 **= $vector2;
    $vector2 = $vector1 ** $scalar;
    $vector2 = $scalar ** $vector1;
    $vector **= $scalar;

Increment
    ++$vector;
    $vector++;

Decrement
    --$vector;
    $vector--;

Lexical Comparison (unsigned)
    $cmp = $vector1 cmp $vector2;
    if ($vector1 lt $vector2)
    if ($vector1 le $vector2)
    if ($vector1 gt $vector2)
    if ($vector1 ge $vector2)

    $cmp = $vector cmp $scalar;
    if ($vector lt $scalar)
    if ($vector le $scalar)
    if ($vector gt $scalar)
    if ($vector ge $scalar)

Comparison (signed)
    $cmp = $vector1  $vector2;
    if ($vector1 < $vector2)  #  depending on configuration
    if ($vector1  $vector2)
    if ($vector1 >= $vector2)

    $cmp = $vector  $scalar;
    if ($vector < $scalar)  #  depending on configuration
    if ($vector  $scalar)
    if ($vector >= $scalar)

Equality
    if ($vector1 eq $vector2)
    if ($vector1 ne $vector2)
    if ($vector eq $scalar)
    if ($vector ne $scalar)

    if ($vector1 == $vector2)
    if ($vector1 != $vector2)
    if ($vector == $scalar)
    if ($vector != $scalar)

Subset Relationship
    if ($vector1 = $vector2)  #  depending on configuration

True Superset Relationship
    if ($vector1 > $vector2)  #  depending on configuration

⚠️ IMPORTANT NOTES

🔢 Boolean values

Boolean values in this module are always a numeric zero (0) for false and a numeric one (1) for true.

➖ Negative numbers

Numeric factors (as needed for the <<, >> and x operators) and bit numbers are always regarded as being unsigned. As a consequence, whenever you pass a negative number, it will be treated as a (usually very large) positive number due to its internal two's complement binary representation, usually resulting in malfunctions or an index out of range error message and program abortion. Note that this does not apply to big integer decimal numbers, which are passed as strings and may be negative.

⚙️ Overloaded operators configuration

The behaviour of certain overloaded operators can be changed via the Configuration() method. For instance, scalars provided as operands are automatically converted to bit vectors internally. These scalars are thereby assumed to be indices or to be in hexadecimal, binary, decimal or enumeration format, depending on the configuration. Similarly, when converting bit vectors to strings using double quotes (""), the output format will also depend on the configuration. Finally, some overloaded operators may have different semantics depending on the configuration; for instance, the operator + can be the union operator from set theory or the arithmetic add operator. In all cases, the defaults have been chosen to be backward compatible.

🔢 Big integers

As long as big integers are small enough so that Perl doesn't need scientific notation, you can provide these constants to the overloaded operators in numeric form. You will get an error message if your big integer numbers exceed that limit. It is strongly recommended that you enclose all your big integer constants in quotes.

$vector /= 10;          #  ok because number is small
$vector /= -10;         #  ok for same reason
$vector /= "10";        #  always correct
$vector += "1152921504606846976";  #  quotes probably required here

All examples assume Bit::Vector->Configuration("input=decimal"); having been set beforehand. This module does not support scientific notation for big integer decimal numbers. The only characters allowed in big integer constant strings are the digits 0..9 and an optional leading sign (+ or -).

✅ Valid operands for overloaded operators

All overloaded operators expect at least one bit vector operand, in order for the operator to know that the overloaded variant is to be used. This is especially true for all unary operators:

"$vector"
if ($vector)
if (!$vector)
~$vector
-$vector
abs($vector)
++$vector
$vector++
--$vector
$vector--

For obvious reasons the left operand (lvalue) of all assignment operators is also required to be a bit vector:

.=
x=
<<=
>>=
|=
&=
^=
+=
-=
*=
/=
%=
**=

In the case of <<, >> and x (and their assignment variants), the left operand is always a bit vector and the right operand is always a number (the factor). In all truly binary operators, one of either operands may be replaced by a Perl scalar (number or string).

The acceptable scalar types for each configuration:

• input = bit indices (default): numeric
• input = hexadecimal: string
• input = binary: string
• input = decimal: string (in general), numeric (if small enough)
• input = enumeration: string

These scalar operands are converted to bit vectors of the same size as the other operand. The only exception is the concatenation operator (.) and its assignment variant (.=): if one operand is a scalar, the remaining bit vector is converted to a string and concatenated (returning a string).

📐 Bit order

Bit vectors are stored least order bit and least order word first internally. Bit #0 corresponds to bit #0 of word #0. When converting to/from (binary or hexadecimal) strings, the rightmost bit is the least significant one, and the leftmost bit is the most significant bit. This matches western representation of numbers.

📏 Matching sizes

In general, for methods involving several bit vectors, all bit vector arguments must have identical sizes (number of bits), or a fatal size mismatch error will occur. Exceptions: Concat(), Concat_List(), Copy(), Interval_Copy() and Interval_Substitute(). In Multiply(), the result bit vector may be larger than the factors. In Power(), the result must be the same size or greater than the base.

🎯 Index ranges

All indices for any given bits must lie between 0 and $vector->Size()-1, or a fatal index out of range error will occur.

🔍 DESCRIPTION

⚙️ Configuration() method

$config = Bit::Vector->Configuration();
Bit::Vector->Configuration($config);
$oldconfig = Bit::Vector->Configuration($newconfig);

This method alters the semantics of certain overloaded operators. It does not affect the C methods. The method accepts an optional string with keywords that influence three aspects:

• Scalar input – how scalars are converted to bit vectors
• Operator semantics – set operations vs arithmetic operations
• String output – format when bit vectors are interpolated in double quotes

The input string may contain assignments of the form <which>=<value>, separated by comma, semicolon, colon, etc. Keywords are case-insensitive and must be unambiguous.

🔧 Scalar Input

• ^bit$, ^index, ^indice – treat scalar as a bit index (default)
• ^hex – treat as hexadecimal string
• ^bin – treat as binary string
• ^dec – treat as decimal integer
• ^enum – treat as enumeration (list of indices/ranges)

🔄 Operator Semantics

• ^set$ – set operations (default): + = union, - = set difference, * = intersection, < = true subset, etc.
• ^arithmetic – arithmetic operations: + = addition, - = subtraction, * = multiplication, < = less than (signed), etc.

🔤 String Output

• ^hex – hexadecimal (default)
• ^bin – binary
• ^dec – decimal
• ^enum – enumeration

Examples:

Bit::Vector->Configuration("in=bin,ops=arithmetic,out=bin");
print Bit::Vector->Configuration(), "\n";

Returns: Scalar Input = Binary, Operator Semantics = Arithmetic Operators, String Output = Binary

📋 $vector (string interpolation)

When a bit vector variable is enclosed in double quotes, it is converted to a string according to the current configuration (default: hexadecimal).

✅ if ($vector)

True if the bit vector contains at least one set bit; false if all bits are cleared.

❌ if (!$vector)

True if all bits are cleared; false if at least one bit is set. (Not the same as is_full().)

🔁 ~$vector (one's complement)

Returns a new bit vector which is the one's complement (invert all bits).

➖ -$vector (unary minus)

Returns a new bit vector which is the two's complement (invert all bits and increment by 1).

📏 abs($vector)

Depending on configuration: either returns the number of set bits (default) or returns a new bit vector with the absolute value of the number stored.

🔗 $vector1 . $vector2 (concatenation)

Returns a new bit vector which is the concatenation of the two operands. If one operand is a scalar, the other is converted to a string and concatenated (returns a string).

🔁 $vector x $factor (duplication)

Returns a new bit vector which is the concatenation of $factor copies of the left operand. If factor is zero, returns a zero-length bit vector.

⬅️ $vector << $bits (shift left)

Returns a new bit vector with bits shifted left by $bits positions. Lost bits are discarded; new bits are zero. If $bits >= size, returns an empty bit vector.

➡️ $vector >> $bits (shift right)

Returns a new bit vector with bits shifted right by $bits positions. Similarly, new bits are zero.

🔀 $vector1 | $vector2 (bitwise OR / union)

Returns a new bit vector which is the bitwise OR of the two operands (set union).

🔀 $vector1 & $vector2 (bitwise AND / intersection)

Returns a new bit vector which is the bitwise AND (set intersection).

🔀 $vector1 ^ $vector2 (bitwise XOR / symmetric difference)

Returns a new bit vector which is the bitwise XOR (symmetric difference of sets).

➕ $vector1 + $vector2 (configurable)

Depending on configuration: set (default) – bitwise OR (union); arithmetic – arithmetic addition.

➖ $vector1 - $vector2 (configurable)

Depending on configuration: set (default) – set difference; arithmetic – arithmetic subtraction.

✖️ $vector1 * $vector2 (configurable)

Depending on configuration: set (default) – bitwise AND (intersection); arithmetic – arithmetic multiplication.

➗ $vector1 / $vector2

Returns a new bit vector containing the result of division of the two numbers.

🔢 $vector1 % $vector2

Returns a new bit vector containing the remainder of division.

🔢 $vector1 ** $vector2

Returns a new bit vector containing the result of exponentiation (left operand raised to the power of the right operand).

➕ $vector1 .= $vector2; (concatenate assignment)

Appends the right operand to the left operand. The left operand is shifted up by the length of the right operand, then the right operand is copied to the freed lower part. If the right operand is a scalar, it is converted to a bit vector of the same size (or of matching length for hex/binary strings).

🔁 $vector x= $factor; (duplicate assignment)

Replaces the bit vector with $factor copies of itself. If factor is zero, resizes to zero length; if one, unchanged.

⬅️ $vector <<= $bits; (shift left assignment)

Shifts the bit vector left by $bits positions. Bits shifted out are lost; new bits are zero. If $bits >= size, the vector is cleared.

➡️ $vector >>= $bits; (shift right assignment)

Shifts the bit vector right by $bits positions. Bits shifted out are lost; new bits are zero. If $bits >= size, the vector is cleared.

🔀 $vector1 |= $vector2; (OR assignment)

Performs bitwise OR and stores result in left operand (set union).

🔀 $vector1 &= $vector2; (AND assignment)

Performs bitwise AND and stores result in left operand (set intersection).

🔀 $vector1 ^= $vector2; (XOR assignment)

Performs bitwise XOR and stores result in left operand (symmetric difference).

➕ $vector1 += $vector2; (configurable)

Depending on configuration: set – bitwise OR (union); arithmetic – arithmetic addition. Stores result in left operand.

➖ $vector1 -= $vector2; (configurable)

Depending on configuration: set – set difference; arithmetic – arithmetic subtraction. Stores result in left operand.

✖️ $vector1 *= $vector2; (configurable)

Depending on configuration: set – bitwise AND (intersection); arithmetic – arithmetic multiplication. Stores result in left operand.

➗ $vector1 /= $vector2; (division assignment)

Stores the result of division in the left operand.

🔢 $vector1 %= $vector2; (modulo assignment)

Stores the remainder of division in the left operand.

🔢 $vector1 **= $vector2; (exponentiation assignment)

Stores the result of exponentiation in the left operand.

➕ ++$vector, $vector++ (increment)

Performs pre- and post-incrementation. Returns a reference to the vector object.

➖ --$vector, $vector-- (decrement)

Performs pre- and post-decrementation. Returns a reference to the vector object.

⚖️ $vector1 cmp $vector2 (unsigned comparison)

Returns -1, 0, or 1 based on unsigned comparison. Supported operators: lt, le, gt, ge (unsigned).

⚖️ $vector1 <=> $vector2 (signed comparison)

Returns -1, 0, or 1 based on signed comparison. Supported operators: <, <=, >, >= (signed, configurable).

🔗 $vector1 eq $vector2 / == (equality)

Returns true if both bit vectors are identical. ne / != returns true if they differ.

🔗 $vector1 <= $vector2 (subset relationship, configurable)

Depending on configuration: set – true if $vector1 is a subset of $vector2; arithmetic – true if less than or equal (signed).

🔗 $vector1 < $vector2 (true subset, configurable)

Depending on configuration: set – true if $vector1 is a true subset; arithmetic – true if less than (signed).

🔗 $vector1 >= $vector2 (superset, configurable)

Depending on configuration: set – true if $vector1 is a superset; arithmetic – true if greater than or equal (signed).

🔗 $vector1 > $vector2 (true superset, configurable)

Depending on configuration: set – true if $vector1 is a true superset; arithmetic – true if greater than (signed).

📚 SEE ALSO

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

📌 VERSION

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

👤 AUTHOR

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

©️ COPYRIGHT

Copyright (c) 2000 - 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 📋 USAGE 📝 SYNOPSIS ⚠️ IMPORTANT NOTES 🔍 DESCRIPTION 📚 SEE ALSO 📌 VERSION 👤 AUTHOR ©️ COPYRIGHT 📄 LICENSE ⚠️ DISCLAIMER