source: project/wiki/eggref/5/bitwise-utils @ 38930

Last change on this file since 38930 was 38930, checked in by Kon Lovett, 2 months ago

rel 1.1.4, add, incomplete, doc

File size: 4.8 KB
Line 
1[[tags: egg]]
2
3== bitwise-utils
4
5[[toc:]]
6
7
8== Documentation
9
10Additional bitwise routines.
11
12=== logical-shift-left
13
14<procedure>(logical-shift-left N1 N2) --> integer</procedure>
15
16Returns left shift of {{N1}} by {{N2}} bits.
17
18; {{N1}} : {{integer}} ; what to shift.
19; {{N2}} : {{fixnum}} ; amount to shift.
20
21Aliases {{arithmetic-shift}}.
22
23=== logical-shift-right
24
25<procedure>(logical-shift-right N1 N2) --> integer</procedure>
26
27Returns right shift of {{N1}} by {{N2}} bits. Sign preserving.
28
29; {{N1}} : {{integer}} ; what to shift.
30; {{N2}} : {{fixnum}} ; amount to shift.
31
32=== arithmetic-shift-left
33
34<procedure>(arithmetic-shift-left N1 N2) --> integer</procedure>
35
36Returns left shift of {{N1}} by {{N2}} bits.
37
38; {{N1}} : {{integer}} ; what to shift.
39; {{N2}} : {{fixnum}} ; amount to shift.
40
41Aliases {{arithmetic-shift}}.
42
43=== arithmetic-shift-right
44
45<procedure>(arithmetic-shift-right N1 N2) --> integer</procedure>
46
47Returns right shift of {{N1}} by {{N2}} bits. Sign extending.
48
49; {{N1}} : {{integer}} ; what to shift.
50; {{N2}} : {{fixnum}} ; amount to shift.
51
52Essentially {{(arithmetic-shift <> (- <>))}}.
53
54=== bitwise-mask
55
56<procedure>(bitwise-mask WID [ON?]) --> integer</procedure>
57
58Returns {{WID}} low-order bits {{ON?}}.
59
60; {{WID}} : {{fixnum}} ; mask bit width.
61; {{ON?]}} : {{boolean}} ; {{#t}} is {{#b1}}, {{#f}} is {{#b0}}; default {{#t}}.
62
63<enscript language=scheme>
64(bitwise-mask 5 #t) ;=> +0...011111 (#b+011111)
65(bitwise-mask 5 #f) ;=> -1...100000 (#b-100000)
66</enscript>
67
68=== bitwise-join
69
70<procedure>(bitwise-join N0 [N1 ...]) --> integer</procedure>
71
72Returns adjoined bits.
73
74; {{N0}} : {{integer}} ; seed.
75; {{N1 ...}} : {{integer ...}} ; adjoins seed left-to-right.
76
77<enscript language=scheme>
78(bitwise-join #b10 #b0000001 #b101) ;=> #b101101
79</enscript>
80
81=== bitwise-split
82
83<procedure>(bitwise-split N WID) --> (list-of integer)</procedure>
84
85Returns {{N}} disjoined every {{WID}} bits.
86
87; {{N}} : {{integer}} ; seed.
88; {{WID}} : {{fixnum}} ; bit width.
89
90<enscript language=scheme>
91(bitwise-split #xabcdef 4) ;=> (#xa #xb #xc #xd #xe #xf)
92(bitwise-split #x-abcdef 4) ;=> (#x-a #x-b #x-c #x-d #x-e #x-f)
93</enscript>
94
95=== bitwise-count
96
97<procedure>(bitwise-count N) --> fixnum</procedure>
98
99Returns number of set bits in {{N}}.
100
101; {{N}} : {{integer}}
102
103=== bitwise-merge
104
105<procedure>(bitwise-merge MASK N0 N1) --> integer</procedure>
106
107; {{MASK}} : {{integer}}
108; {{N0}} : {{integer}}
109; {{N1}} : {{integer}}
110
111{{SRFI-60}} {{bitwise-if}}
112
113=== bitwise-nth?
114
115<procedure>(bitwise-nth? INDEX N) --> boolean</procedure>
116
117; {{INDEX}} : {{integer}}
118; {{N}} : {{fixnum}}
119
120{{SRFI-60}} {{bit-set?}}
121
122=== bitwise-any?
123
124<procedure>(bitwise-any? N1 N2) --> boolean</procedure>
125
126; {{N1}} : {{integer}}
127; {{N2}} : {{integer}}
128
129{{SRFI-60}} {{any-bits-set?}}
130
131=== bitwise-first-set
132
133<procedure>(bitwise-first-set N) --> fixnum</procedure>
134
135; {{N}} :integer
136
137{{SRFI-60}} {{first-set-bit}}
138
139=== bitwise-reverse
140
141<procedure>(bitwise-reverse N K) --> integer</procedure>
142
143; {{N}} :integer
144; {{K}} :fixnum
145
146=== bitwise-rotate
147
148<procedure>(bitwise-rotate TO INDEX LEN) --> integer</procedure>
149
150; {{TO}} : {{integer}}
151; {{INDEX}} : {{fixnum}}
152; {{LEN}} : {{fixnum}}
153
154=== bitwise-set-nth
155
156<procedure>(bitwise-set-nth TO INDEX ON?) --> integer</procedure>
157
158; {{TO}} : {{integer}}
159; {{INDEX}} : {{fixnum}}
160; {{ON?}} : {{boolean}} ; {{#t}} is {{#b1}}, {{#f}} is {{#b0}}
161
162{{SRFI-60}} {{(copy-bit k n b)}}; note argument order change
163
164=== bitwise-field
165
166<procedure>(bitwise-field N START END) --> integer</procedure>
167
168; {{N}} : {{integer}}
169; {{START}} : {{fixnum}}
170; {{END}} : {{fixnum}}
171
172{{SRFI-60}} {{bit-field}}
173
174=== bitwise-field-copy
175
176<procedure>(bitwise-field-copy TO FROM START END) --> integer</procedure>
177
178; {{TO}} : {{integer}}
179; {{FROM}} :  integer
180; {{START}} : {{fixnum}}
181; {{END}} : {{fixnum}}
182
183{{SRFI-60}} {{copy-bit-field}}
184
185=== bitwise-field-reverse
186
187<procedure>(bitwise-field-reverse N START END) --> integer</procedure>
188
189; {{N}} : {{integer}}
190; {{START}} : {{fixnum}}
191; {{END}} : {{fixnum}}
192
193{{SRFI-60}} {{reverse-bit-field}}
194
195<procedure>(bitwise-field-rotate N COUNT START END) --> integer</procedure>
196
197; {{N}} : {{integer}}
198; {{COUNT}} : {{fixnum}}
199; {{START}} : {{fixnum}}
200; {{END}} : {{fixnum}}
201
202{{SRFI-60}} {{rotate-bit-field}}
203
204=== integer->list
205
206<procedure>(integer->list K [LEN]) --> (list-of fixnum)</procedure>
207
208; {{K}} : {{integer}}
209; {{LEN}} : {{(or false fixnum)}} ; {{#f}} is all bits, otherwise number of bits
210
211=== list->integer
212
213<procedure>(list->integer BOOLS) --> integer</procedure>
214
215; {{BOOLS}} : {{list}} ; treated as {{(list-of boolean-like)}}
216
217
218=== Usage
219
220<enscript language=scheme>
221(import bitwise-utils)
222</enscript>
223
224
225== Author
226
227[[/users/kon-lovett|Kon Lovett]]
228
229
230== Version history
231
232; 1.1.4: Fix {{integer->list}} type.
233; 1.1.3 : .
234; 1.1.2 : .
235; 1.1.1 : .
236; 1.1.0 : Add {{srfi-60}} module.
237; 1.0.1 : .
238; 1.0.0 : Release.
239
240
241== License
242
243This code is in the public domain.
Note: See TracBrowser for help on using the repository browser.