NOCL_Bit_List

(Concept - Properties - Functions) 

Version: 1.0 (Older Versions)

Location: cl_objects.php

This class breaks a byte into bits (up to 64 of them) and enables manipulation at the bit level or the byte level.

 

Concept

There is a need to hold onto a number, and be able to access the individual bits within it. 

This class will hold that number and allow updating of individual bits, which all effect the total as well

 

Properties

• • • $decInt
       - (Private) The decimal integer value of this number
      
      
    • $maxBits
       - (Private) The maximum number of bits this object can represent
      
      
    • $bitArr
       - (Private) Array containing each individual bit value; 

 

Functions

• • • __construct()
    • peek()
    • turnBitOn()
    • turnBitOff()
    • toggleBit()
    • ensureSize()
    • modifyBit()
    • calculateInteger()
    • decIntValue()
    • setNewValue()
    • byteSize()
    • onBits()

 

__construct()

Version: 1.0

Called when class is instantiated

Usage:

$byteObject = new NOCL_Bit_List( [ $integerValue ] );

 

Paramenters:

• • • • • $integerValue
          - (Optional) The number this class should initily be set up with as a value. Blank is presumed to mean 0.

 

Returns:

Silently after setting property values internally.  Actually, returns this class as an object.

 

Process:

• • • • • Instantiate a new NOBL_Bit_List
          
          
        • If a value is passed as a parameter to this new class
          
          
          • Set the object values according to the submitted value
            
            
        • Return silently.

 

Peek()

Version: 1.0

Have a look at, and get the value of an individual bit

Usage:

$boolVar = $bitListObject->peek( $bitNumber );

 

Paramenters:

• • • • • $bitNumber
           - Starting from 1, the bit number to look at

 

Returns:

0 or 1 depending on value, or -1 if there's a failure

 

Process:

• • • • • If the requested bit is with the bounds of the object array
          • • Return the value of the requested bit. 
          • Otherwise
            • Return -1

 

turnBitOn()

Version: 1.0

Turn on the value of a bit.

Usage:

$byteObj->turnBitOn( $bit Number );

 

Paramenters:

• • • • • $bitNumber
           - The number, starting from 1, of the bit in question

 

Returns:

False on unsuccessful completion, otherwise silent.

 

Process:

• • • • • If the requested bit is with the bounds of the object array
          • • Run function to modify bit to be on
          • Otherwise
            • Return False

 

turnBitOff()

Version: 1.0

Turn on the value of a bit.

Usage:

$byteObj->turnBitOff( $bit Number );

 

Paramenters:

• • • • • $bitNumber
           - The number, starting from 1, of the bit in question
          
          

 

Returns:

False on unsuccessful completion, otherwise silent.

 

Process:

• • • • • If the requested bit is with the bounds of the object array
          • • Run function to modify bit to be off
          • Otherwise
            • Return False

 

toggleBit()

Version: 1.0

Turn on the value of a bit, or off, depending on whether its alreay off or on..

Usage:

$ResultInt = $byteObj->toggleBit( $bit Number );

 

Paramenters:

• • • • • $bitNumber
           - The number, starting from 1, of the bit in question
          
          

Returns:

False on unsuccessful completion, otherwise silent.

 

Process:

• • • • • If the requested bit is with the bounds of the object array
          • • Run function to modify bit to toggle
          • Otherwise
            • Return False

 

byteSize()

Version: 1.0

Returns the number of bits, rounded up to the nearest multiple of 8,  This way if the byte is 3 bytes long, there will be 24 bits.

Usage:

$numberOfBits = $byteObj->byteSize( $maxBit );

 

Paramenters:

• • • • • $maxBit
           - The current largest bit number

 

Returns:

The number of bits that make up the byte(s)

 

Process:

• • • • • Divide $maxBit by 8.
          
          
        • Round down to the nearest integer.
          
          
        • add 1 to the integer
          
          
        • Multiply by 8
          
          
        • Return that result

 

ensureSize()

Version: 1.0

Make sure a byte is no larger or smaller than needed by a given byte number

Usage:

$bitList->ensureSize( $bitNumber );

 

Paramenters:

• • • • • $bitNumber
           - The maximum needed bit number.  Result will equal this or be larger.

 

Returns:

Silently

 

Process:

• • • • • Increase as necessary $bitNumber to include its whole containing byte
          
          
        • While the count of class bit array elements ($this->bitArr) is less than $bitNumber
          
          
          • Add an array element with the value of 0
            
            
        • Trim the array down to a maximum size of $bitNumber

 

modifyBit()

Version: 1.0

Change the value of a bit to on, off, or the opposite of what it is now

Usage:

$bitList->modifyBit( $bitNumber, $newValue );

 

Paramenters:

• • • • • $bitNumber
           - The number, starting from 1, of the bit in question
          
          
        • $newValue
           - 0, 1, or 2.  0 is Off, 1 is On and 2 is Toggle

 

Returns:

Silently

 

Process:

• • • • • If the $bitNumber is bigger than the current maximum number of bits
          
          • Change $bitNumber to equal the maximum number of bits
        • If this is a toggle action
          
          • • Toggle the bit
          • Otherwise
            
            • Set the bit to 0 or 1, depending on what was sent through as a new value.
        • Recalculate the class integer ($this->decInt)

 

calculateInteger()

Version: 1.0

Calculate and set the current integer, based on current bit values

Usage:

$bitList->calculateInteger();

 

Paramenters:

None

 

Returns:

Silently

 

Process:

• • • • • Set a return value of 0
          
        • If there's more than 0 bit items
          
          
          • If the value of the first bit is 1
            
            
            • add 1 to the return value
          • If there's more than 1 bit in the list
            
            • For every one of them
              
              • Add its value to return value
              • double the add value for the next one
        • set $this->decInt = return value

 

decIntValue()

Version: 1.0

The value of this byte expressed as a decimal (base 10) integer

Usage:

$decimalInteger = $bitListObject->decIntValue();

 

Paramenters:

 None

 

Returns:

The decimal integer value of this byte

 

Process:

• • • • • Take the $this->decInt and return its value

 

setNewValue()

Version: 1.0

Set bit values based on an input number

Usage:

$bitListObject->setNewValue( $newValue );

 

Paramenters:

• • • • • $newValue
           - The decimal number to set the new value to

 

Returns:

Silently

 

Process:

• • • • • Take the $newValue and set its bits, etc.  Its a proceess.  Look at the code. I have to make dinner.

 

 

 

onBits()

Version: 1.0

An array containing the indexes of any bits that are turned on.

Usage:

$arrayOfIDsOfBitsThatAreOn = $bitListObject->onBits();

 

Paramenters:

None

 

Returns:

An array where the values are the bit number (starting at 1) from this object of each true value

 

Process:

• • • • • Create an empty Array for Output
          
          
          • For each element in the Bit Array
            
            • If the value is true
              
              • Add its bit number to the Output Array
        • Return the Output Array