BitHelpers: what changed

Revision 2 to 3. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		# About
2	2
3	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	4
5	5		Homepage: <https://bitbucket.org/avra/bithelpers>
6	6
7	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	8
9	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	10
11	11		# Installation
12	12
13	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	14
15	15		# Usage
16	16
17	17		## TBooleanBitHelper
18	18
19	19		Example code and it's output:
20	20
21	21		``` pascal
22	22		uses
23	23		bithelpers;
24	24		...
25	25		procedure TForm1.BooleanBitTestBtnClick(Sender: TObject);
26	26		var
27	27		MyBool: boolean;
28	28		begin
29	29		MyBool := true;
30	30		Memo1.Append(MyBool.ToOneZeroString);
31	31		Memo1.Append(MyBool.ToOnOffString); // default is scfUnchangedCase and can be ommited
32	32		Memo1.Append(MyBool.ToOnOffString(scfLowerCase));
33	33		Memo1.Append(MyBool.ToTrueFalseString(scfUpperCase));
34	34		Memo1.Append(MyBool.ToString('OnState', 'OffState')); // true/false custom strings
35	35		Memo1.Append(MyBool.ToString('Укључено', 'Искључено', scfUpperCase)); // when case and unicode matter
36	36		end;
37	37		```
38	38
39		-	~~```~~
	39	+	```text
40	40		1
41	41		On
42	42		on
43	43		TRUE
44	44		OnState
45	45		УКЉУЧЕНО
46	46		```
47	47
48	48		## TByteBitHelper
49	49
50	50		Example code and it's output:
51	51
52	52		``` pascal
53	53		procedure TForm1.ByteBitTestBtnClick(Sender: TObject);
54	54		var
55	55		MyByte: byte;
56	56		begin
57	57		MyByte.Clear; // %00000000 MyByte equals 0
58	58		MyByte.Bit[0] := true; // %00000001 MyByte equals 1
59	59		MyByte.Bit[2] := true; // %00000101 MyByte equals 5
60	60		Memo1.Append(MyByte.ToString);
61	61		Memo1.Append('$' + MyByte.ToHexString);
62	62		Memo1.Append(MyByte.ToBinString(lzHideLeadingZeros)); // hide leading zeros
63	63		Memo1.Append(MyByte.ToBinString); // show leading zeros
64	64		end;
65	65		```
66	66
67		-	~~```~~
	67	+	```text
68	68		5
69	69		$05
70	70		101
71	71		00000101
72	72		```
73	73
74	74		## TWordBitHelper
75	75
76	76		Example code and it's output:
77	77
78	78		``` pascal
79	79		procedure TForm1.WordBitTestBtnClick(Sender: TObject);
80	80		var
81	81		MyWord: word;
82	82		begin
83	83		MyWord.Clear; // %0000000000000000 MyWord equals 0
84	84		MyWord.Byte[0] := 2; // %0000000000000010 MyWord equals 2
85	85		MyWord.Byte[1] := 1; // %0000000100000010 MyWord equals 258 (2 + 256)
86	86		MyWord.Byte[1].Bit[7] := true; // %0000000100000010 MyWord equals 258 (Beware!!! This DOES NOT set a bit in MyWord !!!)
87	87		MyWord.Bit[10] := true; // %0000010100000010 MyWord equals 1282 (258 + 2^10)
88	88		Memo1.Append(MyWord.ToString);
89	89		Memo1.Append('$' + MyWord.ToHexString);
90	90		Memo1.Append(MyWord.ToBinString(lzHideLeadingZeros)); // hide leading zeros
91	91		Memo1.Append(MyWord.ToBinString); // show leading zeros
92	92		end;
93	93		```
94	94
95		-	~~```~~
	95	+	```text
96	96		1282
97	97		$0502
98	98		10100000010
99	99		0000010100000010
100	100		```
101	101
102	102		## TLongwordBitHelper
103	103
104	104		Example code and it's output:
105	105
106	106		``` pascal
107	107		procedure TForm1.LongwordBitTestBtnClick(Sender: TObject);
108	108		var
109	109		MyLongword: longword;
110	110		begin
111	111		MyLongword.Clear; // %00000000000000000000000000000000 MyLongword equals 0
112	112		MyLongword.Word[0] := 250; // %00000000000000000000000011111010 MyLongword equals 250
113	113		MyLongword.Word[1].Byte[0] := 100; // %00000000000000000000000011111010 MyLongword equals 250 (Beware!!! This DOES NOT set a byte in MyLongword !!!)
114	114		MyLongword.Byte[1] := 4; // %00000000000000000000010011111010 MyLongword equals 1274 (250 + 2^(8 + 2), 2^2 = 4)
115	115		MyLongword.Bit[26] := true; // %00000100000000000000010011111010 MyLongword equals 67110138 (1274 + 2^26)
116	116		Memo1.Append(MyLongword.ToString);
117	117		Memo1.Append('$' + MyLongword.ToHexString);
118	118		Memo1.Append(MyLongword.ToBinString(lzHideLeadingZeros)); // hide leading zeros
119	119		Memo1.Append(MyLongword.ToBinString); // show leading zeros
120	120		Memo1.Append('');
121	121		end;
122	122		```
123	123
124		-	~~```~~
	124	+	```text
125	125		67110138
126	126		$040004FA
127	127		100000000000000010011111010
128	128		00000100000000000000010011111010
129	129		```
130	130
131	131		## TQuadwordBitHelper
132	132
133	133		Example code and it's output:
134	134
135	135		``` pascal
136	136		procedure TForm1.QuadwordBitTestBtnClick(Sender: TObject);
137	137		var
138	138		MyQuadword: qword;
139	139		begin
140	140		MyQuadword.Clear; // %0000000000000000000000000000000000000000000000000000000000000000 MyQuadword equals 0
141	141		MyQuadword.Longword[0] := 12345; // %0000000000000000000000000000000000000000000000000011000000111001 MyQuadword equals 12345
142	142		MyQuadword.Longword[1].Word[0] := 100; // %0000000000000000000000000000000000000000000000000011000000111001 MyQuadword equals 12345 (Beware!!! This DOES NOT set a word in MyQuadword !!!)
143	143		MyQuadword.Byte[3] := 2; // %0000000000000000000000000000000000000010000000000011000000111001 MyQuadword equals 33566777 (12345 + 2^(8 + 8 + 8 + 2), 2^1 = 2)
144	144		MyQuadword.Bit[50] := true; // %0000000000000100000000000000000000000010000000000011000000111001 MyQuadword equals 1125899940409401 (33566777 + 2^50)
145	145		Memo1.Append(MyQuadword.ToString);
146	146		Memo1.Append('$' + MyQuadword.ToHexString);
147	147		Memo1.Append(MyQuadword.ToBinString(lzHideLeadingZeros)); // hide leading zeros
148	148		Memo1.Append(MyQuadword.ToBinString); // show leading zeros
149	149		end;
150	150		```
151	151
152		-	~~```~~
	152	+	```text
153	153		1125899940409401
154	154		$0004000002003039
155	155		100000000000000000000000010000000000011000000111001
156	156		0000000000000100000000000000000000000010000000000011000000111001
157	157		```
158	158
159	159		## TQuadwordOverlay, TLongwordOverlay, TWordOverlay and TByteOverlay
160	160
161	161		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:
162	162
163	163		``` pascal
164	164		procedure TForm1.OverlaysTestBtnClick(Sender: TObject);
165	165		var
166	166		MyQuadOverlay: TQuadwordOverlay;
167	167		begin
168	168		MyQuadOverlay.AsQuadword.Clear;
169	169		MyQuadOverlay.AsByte[0] := 100;
170	170		Memo1.Append(MyQuadOverlay.AsQuadword.ToBinString);
171	171		MyQuadOverlay.AsLongword[1] := 1;
172	172		Memo1.Append(MyQuadOverlay.AsQuadword.ToBinString);
173	173		MyQuadOverlay.AsQuadword.Bit[32] := false;
174	174		Memo1.Append(MyQuadOverlay.AsQuadword.ToBinString);
175	175		MyQuadOverlay.AsWordOverlay[3].AsByte[1] := $FF; // recursive overlays are allowed
176	176		Memo1.Append(MyQuadOverlay.AsQuadword.ToBinString);
177	177		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
178	178		Memo1.Append(MyQuadOverlay.AsQuadword.ToBinString);
179	179		MyQuadOverlay.AsBit[63] := false;
180	180		Memo1.Append(MyQuadOverlay.AsQuadword.ToBinString);
181	181		end;
182	182		```
183	183
184		-	~~```~~
	184	+	```text
185	185		0000000000000000000000000000000000000000000000000000000001100100
186	186		0000000000000000000000000000000100000000000000000000000001100100
187	187		0000000000000000000000000000000000000000000000000000000001100100
188	188		1111111100000000000000000000000000000000000000000000000001100100
189	189		1111111100000000000000000000000000000000000000000000000001100100
190	190		0111111100000000000000000000000000000000000000000000000001100100
191	191		```
192	192
193	193		## HighestBitPos(), LowestBitPos() and BitsCount()
194	194
195	195		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:
196	196
197	197		``` pascal
198	198		procedure TForm1.BitsPosAndCountClick(Sender: TObject);
199	199		var
200	200		MyQuadWord: qword;
201	201		begin
202	202		MyQuadWord := $7F00000000000064; // 0111111100000000000000000000000000000000000000000000000001100100
203	203		Memo1.Append(MyQuadword.ToBinString);
204	204		Memo1.Append('MyQuadword.HighestBitPos = ' + MyQuadword.HighestBitPos.ToString);
205	205		Memo1.Append('MyQuadword.LowestBitPos = ' + MyQuadword.LowestBitPos.ToString);
206	206		Memo1.Append('MyQuadword.BitsCount = ' + MyQuadword.BitsCount.ToString);
207	207		Memo1.Append('');
208	208		end;
209	209		```
210	210
211		-	~~```~~
	211	+	```text
212	212		0111111100000000000000000000000000000000000000000000000001100100
213	213		MyQuadword.HighestBitPos = 62
214	214		MyQuadword.LowestBitPos = 2
215	215		MyQuadword.BitsCount = 10
216	216		```
217	217
218	218		## ToBinString custom formatting
219	219
220	220		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:
221	221
222	222		``` pascal
223	223		procedure TForm1.TmpFormatBtnClick(Sender: TObject);
224	224		var
225	225		MyQuadWord: qword;
226	226		MyTmpFormat: THelperFormatSettings;
227	227		begin
228	228		MyQuadWord := 1125899940409401;
229	229
230	230		MyTmpFormat.PrefixString := '< ';
231	231		MyTmpFormat.SufixString := ' >';
232	232		MyTmpFormat.ByteSeparator := ' - ';
233	233		MyTmpFormat.WordSeparator := ' = ';
234	234		MyTmpFormat.LongwordSeparator := ' ';
235	235		MyTmpFormat.NibbleSeparator := '.';
236	236
237	237		Memo1.Append('MyQuadword.ToBinString(MyTmpFormat, true);');
238	238		Memo1.Append(MyQuadword.ToBinString(MyTmpFormat, true)); // true is default so it can be ommited and leading zeros will still be shown
239	239		Memo1.Append('MyQuadword.Longword[1].ToBinString(MyTmpFormat);');
240	240		Memo1.Append(MyQuadword.Longword[1].ToBinString(MyTmpFormat)); // default true is ommited, show higher longword with leading zeros
241	241		Memo1.Append('MyQuadword.Word[3].ToBinString(MyTmpFormat, false);');
242	242		Memo1.Append(MyQuadword.Word[3].ToBinString(MyTmpFormat, false)); // show highest word without leading zeros
243	243		end;
244	244		```
245	245
246		-	~~```~~
	246	+	```text
247	247		MyQuadword.ToBinString(MyTmpFormat, true);
248	248		< 0000.0000 - 0000.0100 = 0000.0000 - 0000.0000 0000.0010 - 0000.0000 = 0011.0000 - 0011.1001 >
249	249		MyQuadword.Longword[1].ToBinString(MyTmpFormat);
250	250		< 0000.0000 - 0000.0100 = 0000.0000 - 0000.0000 >
251	251		MyQuadword.Word[3].ToBinString(MyTmpFormat, false);
252	252		< 100 >
253	253		```
254	254
255	255		and then permanent format example:
256	256
257	257		``` pascal
258	258		procedure TForm1.ChangeFormatBtnClick(Sender: TObject);
259	259		var
260	260		MyQuadWord: qword;
261	261		begin
262	262		MyQuadWord := 1125899940409401;
263	263
264	264		// all DefaultHelperFormatSettings fields are empty strings by default, so we change them here:
265	265		DefaultHelperFormatSettings.PrefixString := '{';
266	266		DefaultHelperFormatSettings.SufixString := '}';
267	267		DefaultHelperFormatSettings.NibbleSeparator := '_';
268	268		DefaultHelperFormatSettings.ByteSeparator := ' ';
269	269		DefaultHelperFormatSettings.WordSeparator := ' ' + Chr(39) + ' '; // single quote
270	270		DefaultHelperFormatSettings.LongwordSeparator := ' " ';
271	271
272	272		Memo1.Append(MyQuadword.ToBinString(true));
273	273		Memo1.Append(MyQuadword.Longword[1].ToBinString);
274	274		Memo1.Append(MyQuadword.Word[3].ToBinString(false));
275	275		end;
276	276		```
277	277
278		-	~~```~~
	278	+	```text
279	279		{0000_0000 0000_0100 ' 0000_0000 0000_0000 " 0000_0010 0000_0000 ' 0011_0000 0011_1001}
280	280		{0000_0000 0000_0100 ' 0000_0000 0000_0000}
281	281		{100}
282	282		```
283	283
284	284		# License
285	285
286	286		BitHelpers package is released under triple license:
287	287
288	288		- [[https://www.gnu.org/licenses/lgpl-3.0.en.html LGPLv3]] - chosen for compatibility with Pasettimino.
289	289		- [[http://wiki.freepascal.org/FPC modified LGPL FPC modified LGPL]] - chosen for compatibility with FreePascal and Lazarus.
290	290		- [[https://opensource.org/licenses/BSD-3-Clause BSD3]] - chosen for compatibility with everything else.
291	291
292	292		---
293	293		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