/
deflate.txt
139 lines (75 loc) · 3.4 KB
/
deflate.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
deflate module documentation
[this is temporary until the documentation is property formatted
and merged with other documentation]
The deflate module provides a stream interface to the widely
available libz compression library. libz is not included and is
assumee to be on your machine.
Functions are in the util.zip package.
The module exports
class:
deflate-stream
functions
deflate-target-stream
deflate-stream-vector
deflate-stream-vector-combined
This module implements the deflate-stream. A deflate-stream
accepts characters and byte and causes them to be compressed
and sent to a target.
The target can either another stream, or it can be a vector.
In the case of a vector the deflate-stream will collect the
complete deflation of what is written to it in a sequence of
vectors, initially using the vector passed in as the target and
then allocating new vectors as necessary.
Usage:
(make-instance 'deflate-stream :target target-spec :compression compress-spec)
The target-spec is a stream or a simple vector element type (unsigned-byte 8).
The compress-spec is either :gzip or :deflate (where :gzip is the default).
:gzip is the preferred format as the result can be uncompressed with
the inflate-stream (be sure to specify :skip-gzip-header t to the
make-instance of inflate-stream). The :gzip format output can
also be uncompressed with the gunzip program fount on Unix.
Stream as a target-spec
If you pass a stream as the target-spec then as you write characters
and bytes to the deflate-stream, the bytes resulting from deflation
will be written to the given stream. There is a lot of buffering
going on in this stream and the compression library. Therefore you
may not see the results in your target-spec stream immeidately.
When you close the deflate-stream the last bytes in all the buffers
will be sent through deflation and the end of deflation record will
be written to the target-spec stream.
The target-spec stream will NOT be closed. It is the callers responsibility
to close the stream passed in as the target-spec
The function
(deflate-target-stream deflate-stream)
will return that target-spec stream used by the deflate-stream
;
Octet vector as a target-spec
Passing a simple vector of type (unsigned-byte 8) as the target-spec
is telling the deflate-stream that you wish to collect the deflation
result in vectors in the lisp heap.
After you close the deflate-stream you can retrieve the result of
deflation in one of two ways:
(deflate-stream-vector-combined deflate-stream)
returns two values
1. octet vector
2. number of bytes of actual data
this says that the result of deflation is found in the first N bytes
of the vector returned by the first value. The second value returned is N.
(deflate-stream-vector deflate-stream)
returns three values
1. the newest vector
2. the number of byte of actual data in the newest vector
3. a list of previous vectors holding data in reverse order
for example if the three returned values were
v
100
(c b a)
then the deflated result is found by combining in this order:
all of a
all of b
all of c
the first 100 bytes of v
The deflate-stream-vector-combined function does the combination
described above to produce its results. This results in
a new vector allocation and then copying that wouldn't be necessary
if you're prepared to work with the raw results from deflate-stream-vector