source: project/release/2/binary-parse/binary-parse.html @ 8742

Last change on this file since 8742 was 8742, checked in by felix winkelmann, 12 years ago

moved eggs partially to rrb2

File size: 3.2 KB
Line 
1<html>
2<head><title>Eggs Unlimited - binary-parse</title>
3<style type="text/css">
4  <!--
5      CODE {
6             color: #666666;
7           }
8      EM {
9           font-weight: bold;
10           font-style: normal;
11         }
12      DT.function { 
13                    background: #f5f5f5;
14                    color: black;
15                    padding: 0.1em;
16                    border: 1px solid #bbbaaf;
17                    font-family: monospace;
18                  }
19      PRE {
20        background: #efeee0;
21        padding: 0.1em;
22        border: 1px solid #bbbaaf;
23      }
24      TABLE {
25        background: #f5f5f5;
26        padding: 0.2em;
27      }
28      TH {
29        border-bottom: 1px solid black;
30      }
31    -->
32</style>
33</head>
34<body>
35
36<center><img src="egg.jpg"></center>
37<center><a href="index.html">back</a></center>
38
39<h2>binary-parse</h2>
40
41<h3>Description:</h3>
42Simple parsing of binary data.
43
44<h3>Author:</h3>
45Oleg Kiselyov
46
47<h3>Version:</h3>
48<ul>
49<li>1.1
50When <code>numbers</code> extension is available, a bignum-aware version is additionally built
51<li>1.0
52</ul>
53
54<h3>Usage:</h3>
55<pre>
56(require-extension binary-parse)
57(require-extension big-binary-parse)   ; when numbers egg is available
58</pre>
59
60<h3>Download:</h3>
61<a href="binary-parse.egg">binary-parse.egg</a>
62
63<h3>Documentation:</h3>
64
65<dl>
66<dt class="function"><em>(procedure)</em> make-bit-reader BYTE-READER</dt>
67<dd>
68<p>
69Given a BYTE-READER (a thunk), construct and return a function <code>bit-reader N</code>
70that reads N bits from a byte-stream represented by the BYTE-READER.
71The BYTE-READER is a function that takes no arguments and returns
72the current byte as an exact integer [0-255]. The byte reader
73should return #f on EOF.
74<p>The bit reader returns N bits as an exact unsigned integer,
750 -... (no limit). N must be a positive integer, otherwise the bit reader
76returns #f. There is no upper limit on N -- other than the size of the
77input stream itself and the amount of (virtual) memory an OS is willing
78to give to your process. If you want to read 1M of _bits_, go ahead.
79<p>
80It is assumed that the bit order is the most-significant bit first.
81<p>Note the bit reader keeps the following condition true at all times:
82<pre>
83        (= current-inport-pos (ceiling (/ no-bits-read 8)))
84</pre>
85That is, no byte is read until the very moment we really need (some of)
86its bits. The bit reader does <i>not</i> "byte read ahead".
87Therefore, it can be used to handle a concatenation of different
88bit/byte streams <b>strictly</b> sequentially, <i>without</i> "backing up a char",
89"unreading-char" etc. tricks.
90<p>Thus careful attention to byte-buffering and optimization are the
91features of this bit reader.
92
93<p>Usage example:
94<pre>
95        (define bit-reader (make-bit-reader (lambda () #b11000101)))
96        (bit-reader 3) ==> 6
97        (bit-reader 4) ==> 2
98</pre>
99
100<p>Notes on the algorithm.
101The function recognizes and handles the following special cases:
102<ul>
103<li>the buffer is empty and 8, 16, 24 bits are to be read
104<li>reading all bits which are currently in the byte-buffer
105   (and then maybe more)
106<li>reading only one bit
107</ul>
108</dd>
109
110</dl>
111
112<h3>License:</h3>
113<pre>
114Copyright (c) Oleg Kiselyov
115
116This code is in the public domain
117</pre>
118
119
120<hr><a href="index.html">back</a>
121
122</body>
123</html>
Note: See TracBrowser for help on using the repository browser.