Tech Note 10: The Bits 'n Bytes Lib

January 14, 2009

© NSB Corporation. All rights reserved.


The BitsNbyteslib adds a number of handy functions to NS Basic for doing bit manipulation and conversions. You can do a variety of bitwise AND, OR and NOT operations, shift bits left and right, and convert between hex, binary and decimal.

To use it, add BitsnBytesLib.prc to your project as a resource. It is a small file, about 7k in size. Initialise it in your startup code as follows: 


     loadLibrary "BitsNBytesLib","BNB"   'case is important

These functions require datatypes to be exactly as defined. Most of the arguments are required to be integers. Integers for these calls are 32 bits. Shorts are 16 bits. They are the same as standard NS Basic integer and short variables. If you use incorrect datatypes, you will get execution errors at runtime.

When calling routines in libraries, it is important to use the correct variable types. The calling routine uses the variable type to properly place the values on the stack to be passed to the library. A call such as 

c=BNB.xorInteger(16,4)
will not work because the library calling routine cannot determine whether 16 and 4 should be short, integer or float datatypes for the call. The call will work properly if you assign 16 and 4 to variables that you use in the function statement: 
dim a as integer
dim b as integer
a=16
b=4
c=BNB.xorInteger(a,b)

BitsnByteslib includes the following files:

  1. BitsNByteslib.prc: put into \nsbasic\downloads and in your project as a resource
  2. BitsNByteslib.INF: put into \nsbasic\lib
  3. BitsNBytes.prj: put into \nsbasic\projects. This is the sample.
  4. BitsNBytes_encript.zip: additional encryption stuff

AndInteger(a,b)

Performs a bitwise AND on A and B and returns the result as an integer. Both arguments must be declared as integers.

Related Functions: AndByte, AndShort

Example


Dim a as Integer
Dim b as Integer
Dim c as Integer
a = 63
b = 4
c = BNB.AndInteger(a,b) ' result is 4

Bin2Dec(A)

Returns string in base 2 converted to an integer in base 10.

Example


Dim a as string
Dim c as Integer
a = "100"
c = BNB.Bin2Dec(a)  ' result is 4

CRC32(buf, count, crc)

Perform a CRC32 check sum calculation on buf. Count is the number of bytes to use in the string and crc is the seed crc value.

Example


Dim buf as String
Dim count as Short
Dim crc as Integer
buf = "Dmitry"
count = Len(buf)
crc = BNB.CRC32(buf,count,b,0)   'result is 168098323

CycleShiftInteger(a,b)

Shift the bits in a by b bit positions. If b is positive, bits are shifted left. If B is negative, they are shifted right. Bits that are moved of the end of the number are rotated to the other end of the number.

Related Functions: CylceShiftByte, CycleShiftShort

Example


Dim a as Integer
Dim b as Short
Dim c as Integer
a = 65536
b = 16
c = BNB.CycleShiftInteger(a,b)  'result is 1

Dec2Bin(a,s)

Convert a value in base 10 to base 2. The second argument should be a string pre-filled to the maximum possible length of the result.

Example


Dim a as Integer
Dim s as String
a = 64
s = "123456781234567812345679812345678"
BNB.Dec2Bin(a,s)   'result is 1000000

Dec2Hex(c,a)

Convert a value in base 10 to a string in base 16. The supplied string needs to be filled with enough characters to contain the result.

Example


Dim a as String
Dim c as Integer
a = "12345678901234567890"
c = 64
BNB.Dec2Hex(c,a)  'a is "40"

EncrpytDES(src, key, dst, enc)

Encrypts or decrypts an 8 byte string using DES. src - input string. Must be 8 characters. key - Encryption key. Must be 8 characters. dst - result string enc - 1 to encrypt, 0 to unencrypt

Example


Dim src as String
Dim dst as String
Dim res as String
Dim key as String
Dim enc as Short
Dim err as Integer


src = "ASDFGHJK"
dst = "!!!!!!!!"
res = "!!!!!!!!"
key = "12345678"

enc=1
err=BNB.EncryptDES(src,key,dst,enc)  'src is encrypted into dst

enc=0
err=BNB.EncryptDES(dst,key,res,enc)  'dst is unencrypted into res

EqvInteger(a,b,mask)

Compares two integers using the following logical expression: (a XOR b) AND mask.

Related Functions: EqvByte, EqvShort

Example


Dim a as Integer
Dim b as Integer
Dim c as Integer
Dim mask as Integer
a = 64
b = 62
mask = 2
c = BNB.EqvInteger(a,b,mask)  'result is 2

GetBitByte(a,b)

Get the value of the bit in position b of byte a.

Related Functions: GetBitInteger, GetBitShort

Example


Dim a as Integer
Dim b as Short
Dim c as Short
a = 64
b = 6
c = BNB.GetBitByte(a,b)  'result is 1

GetBitShort(a,b)

Get the value of the bit in position b of short a.

Related Functions: GetBitByte, GetBitInteger

Example


Dim a as Integer
Dim b as Short
Dim c as Short
a = 64
b = 6
c = BNB.GetBitShort(a,b)  'result is 1

GetBitInteger(a,b)

Get the value of the bit in position b of integer a.

Related Functions: GetBitByte, GetBitShort

Example


Dim a as Integer
Dim b as Short
Dim c as Short
a = 64
b = 6
c = BNB.GetBitInteger(a,b)  'result is 1

GetLowWord(a)

Get the bottom 16 bits of an integer.

Related Functions: GetHiWord, GetLowByte, GetHiByte

Example


Dim a as Integer
Dim c as Short
a = 65537
c = BNB.GetLowWord(a)  'result is 1

Hex2dec(a)

Convert a number in base 16 to base 10.

Example


Dim a as Integer
Dim c as String
C = "40"
A = BNB.Hex2Dec(C)  'result is 64

InverseBitInteger(a,b)

Toggles bit b in integer a.

Related Functions: InverseBitByte, InverseBitShort

Example


Dim a as Integer
Dim b as Short
Dim c as Integer
a = 3
b = 1
c = BNB.InverseBitInteger(a,b) 'result is 1

NotInteger(a)

Toggles the setting of all bits.

Related Functions: NotByte, NotShort

Example


Dim a as Integer
Dim c as Integer
a = 32767
c = BNB.NotInteger(a)  'result is -32768

OrInteger(a,b)

Compares the two integers bit by bit. If either or both have a bit set, the result has the bit set.

Related Functions: OrByte, OrShort

Example


Dim a as Integer
Dim b as Integer
Dim c as Integer
a = 3
b = 9
c = BNB.OrInteger(a,b)  'result is 11

ResetBitInteger(a,b)

Sets bit b to 0 in integer a.

Related Functions: ResetBitByte, ResetBitShort

Example


Dim a as Integer
Dim b as Short
Dim c as Integer
a = 3
b = 0
c = BNB.ResetBitInteger(a,b) 'result is 2

SetBitInteger(a,b)

Sets bit b to 1 in integer a.

Related Functions: SetBitByte, SetBitShort

Example


Dim a as Integer
Dim b as Short
Dim c as Integer
a = 2
b = 0
c = BNB.SetBitInteger(a,b)  'result is 3

SetLowWord(a,b)

Replaces the lower 2 bytes of a with b.

Related Functions: SetHiWord, SetLowByte, SetHighByte

Example


Dim a as Integer
Dim b as Short
Dim c as Integer
a = INT(VAL(FldA.text))
b = INT(VAL(FldB.text))
c = BNB.SetLoWord(a,b)

ShiftInteger(a,b)

Shift the bits in a by b bit positions. If B is positive, bits are shifted left. If B is negative, they are shifted right. Bits that are moved of the end of the number are lost. Zero bits are put into the positions that are opened up at the other end of a.

Related Functions: ShiftByte, ShiftShort

Example


Dim a as Integer
Dim b as Short
Dim c as Integer
a = 65536
b = 16
c = BNB.ShiftInteger(a,b)  'result is 0

SignShiftInteger(a,b)

Shift the bits in a by b bit positions without affecting the sign bit. If A if positive, bits are shifted left. If B is negative, they are shifted right. Bits that are moved of the end of the number are lost. Zero bits are put into the positions that are opened up at the other end of a.

Related Functions: SignShiftByte, SignShiftShort

Example


Dim a as Integer
Dim b as Short
Dim c as Integer
a = -4
b = 2
c = BNB.SignShiftInteger(a,b)  'result is -16

Swap16(a)

Swaps two bytes of a Short. Use for converting data between big endian and little endian systems.

Example


Dim A as Short
Dim B as Short
A = 256
b=BNB.Swap16(a)  'B will be 1. (&h01  -> $h01)

Swap32(a)

Swaps first two bytes of an integer with last 2 bytes. Use for converting data between big endian and little endian systems.

Example


Dim A as Integer
Dim B as Integer
A = 32768
B=BNB.Swap32(a)   'B will be 1. (&h0100  -> $h0001)

Swap64(a)

Swaps first four bytes of an double or float with last 4 bytes. Use for converting data between big endian and little endian systems. The result will not make sense in NS Basic, since it will not follow the format of a float value.

Example


Dim A as Double
Dim B as Double
A = 32768
B=BNB.Swap64(a)

Version()

Returns the version number of BitsnByteslib

Example


Dim c as Short
c = BNB.Version()  'result is 1

XorInteger(a,b)

Compares the arguments bit by bit. If a bit is set in either, but not both, it is set in the result.

Related Functions: XorByte, XorShort

Example


Dim a as Integer
Dim b as Integer
Dim c as Integer
a = 3
b = 9
c = BNB.XorInteger(a,b)  'result is 10

Encryption of longer strings

The standard EncrpytDES function is limited in how long a string it can encrypt as well as by issues with nulls in the string. These functions allow longer strings to be encrypted. (Thanks to Ron Glowka).

Code is also provide to encrypt and decrypt data on the Windows desktop. This code is in \nsbasic\tools\BitsNBytes_encrypt.zip.

SetDESKey keyStr

Establishes the encryption or decryption key to be used with the EncryptDESString() and DecryptDESString() functions. This key value must be set before using these functions. Once set, it will be used for all subsequent operations or until the program ends. If the length of the key is 8 characters or less, standard DES encryption will be used. If the key length is from 9 to 24 characters, Triple-DES encryption is used.

Example


Dim keyStr as String
keyStr = "secret"
BNB.SetDESKey keystr

EncryptDESString(plainText)

Returns the encrypted value of the plainText string. The plainText string can not be more than 248 characters in length. The length of the encrypted string may be up to 9 characters longer than the plainText string. Note: the SetDESKey subroutine must have been called at least once prior to calling this function.

Example


Dim plainText as String
Dim encryptedText as String
plainText = "The quick brown fox jumps over the lazy dog!"
encryptedText = BNB.EncryptDESString(plainText)

DecryptDESString(encryptedText)

Returns the plain text value of the encryptedText string. The encryptedText string can not be more than 250 characters in length. Note: the SetDESKey subroutine must have been called at least once prior to calling this function.

Example


Dim encryptedText as String
Dim plainText as String
plainText = BNB.DecryptDESString(encryptedText)

Encryption/Decryption component for the Windows Desktop

There is a Windows component of the EncryptDESString() and DecryptDESString() functions. This component is implemented as a Windows DLL file and can be called from Visual Basic/VBA and Visual C/C++. Its purpose is to allow a desktop program to encrypt or decrypt data using the same algorithms as the BitsNbytesLib routines.

To use it, the EncDec.dll file must be placed in a system directory or some directory that is currently in your PATH. For Visual Basic/VBA, include the EncDec.bas module. For Visual C/C++, include the EncDec.h header file and link with the EncDec.lib library (note that the EncDec.dll is still required).

The EncDec DLL functions have the same restrictions as their BitsNbytes library counterparts. The main differences are that you specify the encryption key with every function call and that the functions return the length of the returned string.

VB/VBA Example


Dim KeyStr As String
Dim DecryptedStr As String
Dim EncryptedStr As String
Dim StrLen As Integer
KeyStr = "secret"
DecryptedStr = "The quick brown fox jumps over the lazy dog!"
StrLen = EncryptData(KeyStr, DecryptedStr, EncryptedStr)
DecryptedStr = ""
StrLen = DecryptData(KeyStr, EncryptedStr, DecryptedStr)

C/C++ Example


char keyStr[25];
char decryptedStr[251];
char encryptedStr[251];
int  len;
strcpy(keyStr, "secret");
strcpy(decryptedStr, "The quick brown fox jumps over the lazy dog!");
len = encryptData(keyStr, decryptedStr, encryptedStr);
strcpy(decryptedStr, "");
len = decryptData(keyStr, encryptedStr, decryptedStr);