Sign in Join
Wiki copytemporary

BitHelpers: what changed

Revision 0 to 1. Removed lines have a minus sign; added lines have a plus sign.

Title: BitHelpers

OldNewLine
1+# About
2+
3+BitHelpers enable additional bit manipulation for qword, longword, word, byte and boolean types which will make your life much easier if you need such a feature.
4+
5+Homepage: <https://bitbucket.org/avra/bithelpers>
6+
7+FreePascal type helpers TBooleanHelper, TByteHelper, TWordHelper, TCardinalHelper and TQWordHelper do not offer much when bit manipulation and presentation are needed. That's where BitHelpers package jumps in, nicely extending mentioned type helpers.
8+
9+IMPORTANT NEWS: I am so glad to announce that BitHelpers are now part of trunk FreePascal RTL. Type helpers for direct access to bit, nibble, byte, word and dword parts in ordinal types are now part of sysutils unit, and customizable boolean, binary and hexadecimal data localized string representation is now part of syshelpers unit. Syntax has been slightly changed to be more in line with FreePascal (using plurals like SomeOrdType.Bits\[3\] instead of old SomeOrdType.Bit\[3\] and similar). More details at <https://gitlab.com/freepascal.org/fpc/source/-/issues/39268> and <https://gitlab.com/freepascal.org/fpc/documentation/-/issues/39267>. From now on, all further development will be in FreePascal trunk. Bitbucket repo will continue to exist only for historical reasons and old code.
10+
11+# Installation
12+
13+While you can simply copy bithelpers unit to your project directory and start using it, the recommended way would be to open "bithelpers_pkg.lpk" package and compile it. That would add BitHelpers source directory to Lazarus and make it available to all your projects.
14+
15+# Usage
16+
17+## TBooleanBitHelper
18+
19+Example code and it's output:
20+
21+``` pascal
22+ uses
23+ bithelpers;
24+ ...
25+ procedure TForm1.BooleanBitTestBtnClick(Sender: TObject);
26+ var
27+ MyBool: boolean;
28+ begin
29+ MyBool := true;
30+ Memo1.Append(MyBool.ToOneZeroString);
31+ Memo1.Append(MyBool.ToOnOffString); // default is scfUnchangedCase and can be ommited
32+ Memo1.Append(MyBool.ToOnOffString(scfLowerCase));
33+ Memo1.Append(MyBool.ToTrueFalseString(scfUpperCase));
34+ Memo1.Append(MyBool.ToString('OnState', 'OffState')); // true/false custom strings
35+ Memo1.Append(MyBool.ToString('Укључено', 'Искључено', scfUpperCase)); // when case and unicode matter
36+ end;
37+```
38+
39+`  1`\
40+`  On`\
41+`  on`\
42+`  TRUE`\
43+`  OnState`\
44+`  УКЉУЧЕНО`
45+
46+## TByteBitHelper
47+
48+Example code and it's output:
49+
50+``` pascal
51+ procedure TForm1.ByteBitTestBtnClick(Sender: TObject);
52+ var
53+ MyByte: byte;
54+ begin
55+ MyByte.Clear; // %00000000 MyByte equals 0
56+ MyByte.Bit[0] := true; // %00000001 MyByte equals 1
57+ MyByte.Bit[2] := true; // %00000101 MyByte equals 5
58+ Memo1.Append(MyByte.ToString);
59+ Memo1.Append('$' + MyByte.ToHexString);
60+ Memo1.Append(MyByte.ToBinString(lzHideLeadingZeros)); // hide leading zeros
61+ Memo1.Append(MyByte.ToBinString); // show leading zeros
62+ end;
63+```
64+
65+`  5`\
66+`  $05`\
67+`  101`\
68+`  00000101`
69+
70+## TWordBitHelper
71+
72+Example code and it's output:
73+
74+``` pascal
75+ procedure TForm1.WordBitTestBtnClick(Sender: TObject);
76+ var
77+ MyWord: word;
78+ begin
79+ MyWord.Clear; // %0000000000000000 MyWord equals 0
80+ MyWord.Byte[0] := 2; // %0000000000000010 MyWord equals 2
81+ MyWord.Byte[1] := 1; // %0000000100000010 MyWord equals 258 (2 + 256)
82+ MyWord.Byte[1].Bit[7] := true; // %0000000100000010 MyWord equals 258 (Beware!!! This DOES NOT set a bit in MyWord !!!)
83+ MyWord.Bit[10] := true; // %0000010100000010 MyWord equals 1282 (258 + 2^10)
84+ Memo1.Append(MyWord.ToString);
85+ Memo1.Append('$' + MyWord.ToHexString);
86+ Memo1.Append(MyWord.ToBinString(lzHideLeadingZeros)); // hide leading zeros
87+ Memo1.Append(MyWord.ToBinString); // show leading zeros
88+ end;
89+```
90+
91+`  1282`\
92+`  $0502`\
93+`  10100000010`\
94+`  0000010100000010`
95+
96+## TLongwordBitHelper
97+
98+Example code and it's output:
99+
100+``` pascal
101+ procedure TForm1.LongwordBitTestBtnClick(Sender: TObject);
102+ var
103+ MyLongword: longword;
104+ begin
105+ MyLongword.Clear; // %00000000000000000000000000000000 MyLongword equals 0
106+ MyLongword.Word[0] := 250; // %00000000000000000000000011111010 MyLongword equals 250
107+ MyLongword.Word[1].Byte[0] := 100; // %00000000000000000000000011111010 MyLongword equals 250 (Beware!!! This DOES NOT set a byte in MyLongword !!!)
108+ MyLongword.Byte[1] := 4; // %00000000000000000000010011111010 MyLongword equals 1274 (250 + 2^(8 + 2), 2^2 = 4)
109+ MyLongword.Bit[26] := true; // %00000100000000000000010011111010 MyLongword equals 67110138 (1274 + 2^26)
110+ Memo1.Append(MyLongword.ToString);
111+ Memo1.Append('$' + MyLongword.ToHexString);
112+ Memo1.Append(MyLongword.ToBinString(lzHideLeadingZeros)); // hide leading zeros
113+ Memo1.Append(MyLongword.ToBinString); // show leading zeros
114+ Memo1.Append('');
115+ end;
116+```
117+
118+`  67110138`\
119+`  $040004FA`\
120+`  100000000000000010011111010`\
121+`  00000100000000000000010011111010`
122+
123+## TQuadwordBitHelper
124+
125+Example code and it's output:
126+
127+``` pascal
128+ procedure TForm1.QuadwordBitTestBtnClick(Sender: TObject);
129+ var
130+ MyQuadword: qword;
131+ begin
132+ MyQuadword.Clear; // %0000000000000000000000000000000000000000000000000000000000000000 MyQuadword equals 0
133+ MyQuadword.Longword[0] := 12345; // %0000000000000000000000000000000000000000000000000011000000111001 MyQuadword equals 12345
134+ MyQuadword.Longword[1].Word[0] := 100; // %0000000000000000000000000000000000000000000000000011000000111001 MyQuadword equals 12345 (Beware!!! This DOES NOT set a word in MyQuadword !!!)
135+ MyQuadword.Byte[3] := 2; // %0000000000000000000000000000000000000010000000000011000000111001 MyQuadword equals 33566777 (12345 + 2^(8 + 8 + 8 + 2), 2^1 = 2)
136+ MyQuadword.Bit[50] := true; // %0000000000000100000000000000000000000010000000000011000000111001 MyQuadword equals 1125899940409401 (33566777 + 2^50)
137+ Memo1.Append(MyQuadword.ToString);
138+ Memo1.Append('$' + MyQuadword.ToHexString);
139+ Memo1.Append(MyQuadword.ToBinString(lzHideLeadingZeros)); // hide leading zeros
140+ Memo1.Append(MyQuadword.ToBinString); // show leading zeros
141+ end;
142+```
143+
144+`  1125899940409401`\
145+`  $0004000002003039`\
146+`  100000000000000000000000010000000000011000000111001`\
147+`  0000000000000100000000000000000000000010000000000011000000111001`
148+
149+## TQuadwordOverlay, TLongwordOverlay, TWordOverlay and TByteOverlay
150+
151+Variant records are also provided for qword, longword, word and byte. Sometimes they are more convenient to use then type helpers, and nothing stops you to mix them when needed. Here is an example code and it's output:
152+
153+``` pascal
154+ procedure TForm1.OverlaysTestBtnClick(Sender: TObject);
155+ var
156+ MyQuadOverlay: TQuadwordOverlay;
157+ begin
158+ MyQuadOverlay.AsQuadword.Clear;
159+ MyQuadOverlay.AsByte[0] := 100;
160+ Memo1.Append(MyQuadOverlay.AsQuadword.ToBinString);
161+ MyQuadOverlay.AsLongword[1] := 1;
162+ Memo1.Append(MyQuadOverlay.AsQuadword.ToBinString);
163+ MyQuadOverlay.AsQuadword.Bit[32] := false;
164+ Memo1.Append(MyQuadOverlay.AsQuadword.ToBinString);
165+ MyQuadOverlay.AsWordOverlay[3].AsByte[1] := $FF; // recursive overlays are allowed
166+ Memo1.Append(MyQuadOverlay.AsQuadword.ToBinString);
167+ MyQuadOverlay.AsWord[3].Byte[1].Bit[5] := false; // NO CHANGE !!! Bit is set in a result byte, not in a byte that belongs to MyQuadOverlay
168+ Memo1.Append(MyQuadOverlay.AsQuadword.ToBinString);
169+ MyQuadOverlay.AsBit[63] := false;
170+ Memo1.Append(MyQuadOverlay.AsQuadword.ToBinString);
171+ end;
172+```
173+
174+`  0000000000000000000000000000000000000000000000000000000001100100`\
175+`  0000000000000000000000000000000100000000000000000000000001100100`\
176+`  0000000000000000000000000000000000000000000000000000000001100100`\
177+`  1111111100000000000000000000000000000000000000000000000001100100`\
178+`  1111111100000000000000000000000000000000000000000000000001100100`\
179+`  0111111100000000000000000000000000000000000000000000000001100100`
180+
181+## HighestBitPos(), LowestBitPos() and BitsCount()
182+
183+HighestBitPos(), LowestBitPos() and BitsCount() are used for getting position of left most bit, right most bit, and number of set bits. Beware that for a value of 0, result of HighestBitPos() and LowestBitPos() will be 255 (unsigned equivalent of -1). Here is an example code and it's output:
184+
185+``` pascal
186+ procedure TForm1.BitsPosAndCountClick(Sender: TObject);
187+ var
188+ MyQuadWord: qword;
189+ begin
190+ MyQuadWord := $7F00000000000064; // 0111111100000000000000000000000000000000000000000000000001100100
191+ Memo1.Append(MyQuadword.ToBinString);
192+ Memo1.Append('MyQuadword.HighestBitPos = ' + MyQuadword.HighestBitPos.ToString);
193+ Memo1.Append('MyQuadword.LowestBitPos = ' + MyQuadword.LowestBitPos.ToString);
194+ Memo1.Append('MyQuadword.BitsCount = ' + MyQuadword.BitsCount.ToString);
195+ Memo1.Append('');
196+ end;
197+```
198+
199+` 0111111100000000000000000000000000000000000000000000000001100100`\
200+` MyQuadword.HighestBitPos = 62`\
201+` MyQuadword.LowestBitPos = 2`\
202+` MyQuadword.BitsCount = 10`
203+
204+## ToBinString custom formatting
205+
206+ToBinString() can follow custom formatting when needed. Binary string output can be changed permanently by modifying fields of DefaultHelperFormatSettings global record, or temporary by creating a record of THelperFormatSettings type, populating it's fields and making it as a parameter of ToBinString(). It will be more clear in following examples - first how to use temporary format:
207+
208+``` pascal
209+ procedure TForm1.TmpFormatBtnClick(Sender: TObject);
210+ var
211+ MyQuadWord: qword;
212+ MyTmpFormat: THelperFormatSettings;
213+ begin
214+ MyQuadWord := 1125899940409401;
215+
216+ MyTmpFormat.PrefixString := '< ';
217+ MyTmpFormat.SufixString := ' >';
218+ MyTmpFormat.ByteSeparator := ' - ';
219+ MyTmpFormat.WordSeparator := ' = ';
220+ MyTmpFormat.LongwordSeparator := ' ';
221+ MyTmpFormat.NibbleSeparator := '.';
222+
223+ Memo1.Append('MyQuadword.ToBinString(MyTmpFormat, true);');
224+ Memo1.Append(MyQuadword.ToBinString(MyTmpFormat, true)); // true is default so it can be ommited and leading zeros will still be shown
225+ Memo1.Append('MyQuadword.Longword[1].ToBinString(MyTmpFormat);');
226+ Memo1.Append(MyQuadword.Longword[1].ToBinString(MyTmpFormat)); // default true is ommited, show higher longword with leading zeros
227+ Memo1.Append('MyQuadword.Word[3].ToBinString(MyTmpFormat, false);');
228+ Memo1.Append(MyQuadword.Word[3].ToBinString(MyTmpFormat, false)); // show highest word without leading zeros
229+ end;
230+```
231+
232+`  MyQuadword.ToBinString(MyTmpFormat, true);`\
233+`  < 0000.0000 - 0000.0100 = 0000.0000 - 0000.0000   0000.0010 - 0000.0000 = 0011.0000 - 0011.1001 >`\
234+`  MyQuadword.Longword[1].ToBinString(MyTmpFormat);`\
235+`  < 0000.0000 - 0000.0100 = 0000.0000 - 0000.0000 >`\
236+`  MyQuadword.Word[3].ToBinString(MyTmpFormat, false);`\
237+`  < 100 >`
238+
239+and then permanent format example:
240+
241+``` pascal
242+ procedure TForm1.ChangeFormatBtnClick(Sender: TObject);
243+ var
244+ MyQuadWord: qword;
245+ begin
246+ MyQuadWord := 1125899940409401;
247+
248+ // all DefaultHelperFormatSettings fields are empty strings by default, so we change them here:
249+ DefaultHelperFormatSettings.PrefixString := '{';
250+ DefaultHelperFormatSettings.SufixString := '}';
251+ DefaultHelperFormatSettings.NibbleSeparator := '_';
252+ DefaultHelperFormatSettings.ByteSeparator := ' ';
253+ DefaultHelperFormatSettings.WordSeparator := ' ' + Chr(39) + ' '; // single quote
254+ DefaultHelperFormatSettings.LongwordSeparator := ' " ';
255+
256+ Memo1.Append(MyQuadword.ToBinString(true));
257+ Memo1.Append(MyQuadword.Longword[1].ToBinString);
258+ Memo1.Append(MyQuadword.Word[3].ToBinString(false));
259+ end;
260+```
261+
262+`  {0000_0000  0000_0100  '  0000_0000  0000_0000  "  0000_0010  0000_0000  '  0011_0000  0011_1001}`\
263+`  {0000_0000  0000_0100  '  0000_0000  0000_0000}`\
264+`  {100}`
265+
266+# License
267+
268+BitHelpers package is released under triple license:
269+
270+- [[https://www.gnu.org/licenses/lgpl-3.0.en.html LGPLv3]] - chosen for compatibility with Pasettimino.
271+- [[http://wiki.freepascal.org/FPC modified LGPL FPC modified LGPL]] - chosen for compatibility with FreePascal and Lazarus.
272+- [[https://opensource.org/licenses/BSD-3-Clause BSD3]] - chosen for compatibility with everything else.
273+
274+---
275+*From the Free Pascal wiki, page "BitHelpers", as it stood on 2022-01-19 after a change by Avra, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).*

Back to history