March Twenty-Fourth 2006 From: Bob Zale, President PowerBASIC, Inc. Subject: Programming with BIT FIELD variables ============================================= Welcome to the latest edition of the PowerBASIC Gazette! In the coming months, we'll continue a series of articles which explore the many new features in PowerBASIC 8 for Windows, as well as the PowerBASIC Console Compiler 4. Today, we'll concentrate on Bit Field variables, which are common to both of the new compilers. Of course, if you still haven't upgraded to these powerful new versions, now's the time to do it! Choose delivery by download, and you could be "up and running" 30 minutes from now! But more about that later... Bit Field Variables =================== PowerBASIC offers a wide range of variable types. Signed. Unsigned. 8-bit, 16-bit, even 32-bit and 64-bit. But, sometimes, that just isn't enough. For example, there are many times when you only need to store a value for true/false or on/off... it takes just one bit to represent the value 0 or 1. Why waste a whole 8-bit variable for that? If you need to represent the day of the week, you might use the values 1 to 7. Those particular values can be represented in just 3 bits. Why waste a whole 8-bit variable for that, too? Well, it's now no longer necessary. Bit Field variables to the rescue! Use them to design your own custom variables, anywhere from 1-bit wide to a full 31-bits. You can pack these variables in a User-Defined Type or Union, one after another, to gain the very best in memory efficiency. You can use them for compatibility, too. They're common in C and C++. The Windows API uses them extensively. Even if you don't need them now, it's good to understand them... and good to know they'll be right at your fingertips the day you find you really need this new power. Bit Field variables come in two flavors, signed and unsigned. Just as with regular integer-class variables, the signed variety can be used to store both positive and negative values, while unsigned are restricted to just positive values. Internally, the signed versions use one bit for the sign, and the remaining bits for the numeric value, while the unsigned use all the bits for the value. Signed Bit Field variables are called SBIT variables, while the unsigned variety are simply called BIT variables. They are only valid as a member of a User-Defined TYPE or UNION, because they are tightly packed, one after another, in order to optimize for the very minimum amount of memory usage. This can be critically important when you create a large array of these data types. As I said earlier, BIT variables are custom variables -- you decide the size, and you decide the format. For example, "BIT * 1" defines a 1-bit unsigned variable which may take the value 0 or 1. The following table shows the range of values which may be stored in Bit Field variables of each possible size. The first two columns list the range for unsigned BIT variables, while the next two columns denote the range for the same size signed SBIT variables: 1 bit -->> 0 to 1 -1 to 0 2 bits -->> 0 to 3 -2 to +1 3 bits -->> 0 to 7 -4 to +3 4 bits -->> 0 to 15 -8 to +7 5 bits -->> 0 to 31 -16 to +15 6 bits -->> 0 to 63 -32 to +31 7 bits -->> 0 to 127 -64 to +63 8 bits -->> 0 to 255 -128 to +127 9 bits -->> 0 to 511 -256 to +255 10 bits -->> 0 to 1023 -512 to +511 11 bits -->> 0 to 2047 -1024 to +1023 12 bits -->> 0 to 4095 -2048 to +2047 13 bits -->> 0 to 8191 -4096 to +4095 14 bits -->> 0 to 16383 -8192 to +8191 15 bits -->> 0 to 32767 -16384 to +16383 16 bits -->> 0 to 65535 -32768 to +32767 17 bits -->> 0 to 131071 -65536 to +65535 18 bits -->> 0 to 262143 -131072 to +131071 19 bits -->> 0 to 524287 -262144 to +262143 20 bits -->> 0 to 1048575 -524288 to +524287 21 bits -->> 0 to 2097151 -1048576 to +1048575 22 bits -->> 0 to 4194304 -2097152 to +2097151 23 bits -->> 0 to 8388608 -4194304 to +4194303 24 bits -->> 0 to 16777215 -8388608 to +8388607 25 bits -->> 0 to 33554431 -16777216 to +16777215 26 bits -->> 0 to 67108863 -33554432 to +33554431 27 bits -->> 0 to 134217727 -67108864 to +67108863 28 bits -->> 0 to 268435455 -134217728 to +134217727 29 bits -->> 0 to 536870911 -268435456 to +268435455 30 bits -->> 0 to 1073741823 -536870912 to +536870911 31 bits -->> 0 to 2147483647 -1073741824 to +1073741823 Of course, you should use care. Just like so-called "regular" variables, if you try to assign a value to a Bit Field variable which is outside the legal range, you get undefined results. So, how are BIT variables defined? As mentioned earlier, they must be a part of a User-Defined TYPE. As the programmer, you get to define the size of the entire field, as well as the BIT variables which make up that field. Each field may be 1, 2, or 4 bytes in size, and there may be any number of these fields in a TYPE. You'll use the word BYTE, WORD, or DWORD to specify the field size: TYPE ByteParts Nybble1 as BIT * 4 in BYTE Nybble2 as BIT * 4 END TYPE In the above example, the phrase "in BYTE" specifies that the field is one byte in total size, and accessible through either of the two 4-bit nybbles. Each of the 4-bit nybbles can store a value in the range of 0 to 15. An alternative could be to use signed variables in a similar structure: TYPE ByteParts Nybble1 as SBIT * 4 in BYTE Nybble2 as SBIT * 4 END TYPE The only difference here is that each of the 4-bit nybbles can store a signed value, in the range of -8 to plus 7. It's really just that easy! What if you need a larger field? No problem... TYPE DWordParts Nybble1 as BIT * 4 in DWORD Nybble2 as BIT * 4 Nybble3 as BIT * 4 Nybble4 as BIT * 4 Nybble5 as BIT * 4 Nybble6 as BIT * 4 Nybble7 as BIT * 4 Nybble8 as BIT * 4 END TYPE Now, the phrase "in DWORD" tells us that the field is a total of four bytes in total size, and it's accessed through any one of the eight member nybbles. Remember, a User-Defined TYPE may contain one bit field, or many bit fields. You're the programmer, so you're in control! Let's say you need to separate a LONG INTEGER variable into its component parts, and you also need to maintain a number of true/false values as well. Here's a simple way to do just that: Type abcd Valu as BIT * 31 in DWORD Sign as SBIT * 1 Flag as BIT * 1 in BYTE Text as BIT * 1 Slot as BIT * 1 Coin as BIT * 1 Dart as BIT * 1 End Type In the above example, the entire TYPE is 5 bytes in size, consisting of seven member variables. You may have noticed that only 5 bits were used in the second bit field. It's perfectly acceptable to leave some bits unused if they're not needed. But be sure you never try to exceed the size... You simply can't fit 9 bits in 1 byte! How do you access BIT and SBIT variables? Just like any other member of a User-Defined TYPE: DIM Structure as abcd Structure.Coin = 1 Structure.Slot = 0 IF ISTRUE Structure.Coin THEN MSGBOX "We have a valid coin." END IF I hope it's now clear that bit field variables can greatly compress your data size. They can make more code self-documenting. They'll give you compatibility with certain "C" code, and assist with the Windows API. Regardless of the application, it's a powerful tool for the programmer... and found only in your favorite brand of BASIC! PowerBASIC Forums ================= Be sure to visit us soon on the web! Remember, the PowerBASIC Forums now sport well over 200,000 messages from programmers just like you. They ask questions, they get answers, so can you. Just click... http://www.powerbasic.com/support/forums/Ultimate.cgi We'd love to see some of your latest code! So would others, and they'll respond in kind! Lots more to follow on the web site... and the next Gazette! Time for a "Hard Break" {smile} =============================== Please indulge me for one moment? If you haven't yet upgraded to the new compilers, now is certainly the time! Check out all the great new features on any of the following pages... PB/CC 4.0: http://www.powerbasic.com/products/pbcc/ PB/WINDOWS 8.0: http://www.powerbasic.com/products/pbdll32/ PowerBASIC FORMS: http://www.powerbasic.com/products/pbforms/ PowerSHIRT 1.0: http://www.powerbasic.com/products/pbshirt/ PB/WIN 8 is attractively priced at $199, while PB/CC 4 is just $169. Upgrades from versions 7 and 3 are just $99 and $89 respectively. PowerBASIC Forms is priced at $99, while the upgrade to version 1.5 is $39. You can order by replying to this email. You can call us today at (800)780-7707 or (941)408-8700, place an e/order on our secure web site (www.powerbasic.com), or even mail it in. But no matter what method you choose, please do it today and do it with confidence. Every product PowerBASIC ships for physical delivery is offered with a money-back guarantee for a full 30 days from the transaction date. PowerBackUp CD's are priced at just $15 each ($4 s&h). The next Gazettes will cover even more... More graphics and printing. THREADED variables for Thread Local Storage. ARRAY ASSIGN. Many new CONSOLE functions. FIELD for dynamic structures. New error processing options. Even KEY functions, DESKTOP, and much, much more. Be sure you have the latest compilers... You won't want to miss this! Regards, Bob Zale, President PowerBASIC Inc. p.s. Don't forget PowerSHIRT version 1.0! The new PowerBASIC T-Shirt! It's a high quality, black T-Shirt, emblazoned with "PowerBASIC.COM", and a personal motto "I Compile Without Compromise". You couldn't be more stylish! The new PowerSHIRT 1.0 is available in sizes M/L/XL/XXL/XXXL, and priced at just $19.95. http://www.powerbasic.com/products/pbshirt/ PowerBASIC, Inc. (800) 780-7707 Sales 1978 S. Tamiami Trail (941) 408-8700 Voice Venice, FL 34293 (941) 408-8820 Fax Visit us on the World Wide Web at www.powerbasic.com Email PowerBASIC Sales: sales@powerbasic.com This newsletter is only sent to e-mail addresses in our subscription list. If you have received this newsletter by mistake or no longer wish to receive it, please send a simple unsubscribe request to gazette@powerbasic.com with your name and zip/postal code. ====================================================================