1// Copyright 2015, Joe Tsai. All rights reserved.
2// Use of this source code is governed by a BSD-style
3// license that can be found in the LICENSE.md file.
4
5// Package compress is a collection of compression libraries.
6package compress
7
8import (
9	"bufio"
10	"io"
11
12	"github.com/dsnet/compress/internal/errors"
13)
14
15// The Error interface identifies all compression related errors.
16type Error interface {
17	error
18	CompressError()
19
20	// IsDeprecated reports the use of a deprecated and unsupported feature.
21	IsDeprecated() bool
22
23	// IsCorrupted reports whether the input stream was corrupted.
24	IsCorrupted() bool
25}
26
27var _ Error = errors.Error{}
28
29// ByteReader is an interface accepted by all decompression Readers.
30// It guarantees that the decompressor never reads more data than is necessary
31// from the underlying io.Reader.
32type ByteReader interface {
33	io.Reader
34	io.ByteReader
35}
36
37var _ ByteReader = (*bufio.Reader)(nil)
38
39// BufferedReader is an interface accepted by all decompression Readers.
40// It guarantees that the decompressor never reads more data than is necessary
41// from the underlying io.Reader. Since BufferedReader allows a decompressor
42// to peek at bytes further along in the stream without advancing the read
43// pointer, decompression can experience a significant performance gain when
44// provided a reader that satisfies this interface. Thus, a decompressor will
45// prefer this interface over ByteReader for performance reasons.
46//
47// The bufio.Reader satisfies this interface.
48type BufferedReader interface {
49	io.Reader
50
51	// Buffered returns the number of bytes currently buffered.
52	//
53	// This value becomes invalid following the next Read/Discard operation.
54	Buffered() int
55
56	// Peek returns the next n bytes without advancing the reader.
57	//
58	// If Peek returns fewer than n bytes, it also returns an error explaining
59	// why the peek is short. Peek must support peeking of at least 8 bytes.
60	// If 0 <= n <= Buffered(), Peek is guaranteed to succeed without reading
61	// from the underlying io.Reader.
62	//
63	// This result becomes invalid following the next Read/Discard operation.
64	Peek(n int) ([]byte, error)
65
66	// Discard skips the next n bytes, returning the number of bytes discarded.
67	//
68	// If Discard skips fewer than n bytes, it also returns an error.
69	// If 0 <= n <= Buffered(), Discard is guaranteed to succeed without reading
70	// from the underlying io.Reader.
71	Discard(n int) (int, error)
72}
73
74var _ BufferedReader = (*bufio.Reader)(nil)
75