1// Copyright (c) 2012, Suryandaru Triandana <syndtr@gmail.com>
2// All rights reserved.
3//
4// Use of this source code is governed by a BSD-style license that can be
5// found in the LICENSE file.
6
7// Package comparer provides interface and implementation for ordering
8// sets of data.
9package comparer
10
11// BasicComparer is the interface that wraps the basic Compare method.
12type BasicComparer interface {
13	// Compare returns -1, 0, or +1 depending on whether a is 'less than',
14	// 'equal to' or 'greater than' b. The two arguments can only be 'equal'
15	// if their contents are exactly equal. Furthermore, the empty slice
16	// must be 'less than' any non-empty slice.
17	Compare(a, b []byte) int
18}
19
20// Comparer defines a total ordering over the space of []byte keys: a 'less
21// than' relationship.
22type Comparer interface {
23	BasicComparer
24
25	// Name returns name of the comparer.
26	//
27	// The Level-DB on-disk format stores the comparer name, and opening a
28	// database with a different comparer from the one it was created with
29	// will result in an error.
30	//
31	// An implementation to a new name whenever the comparer implementation
32	// changes in a way that will cause the relative ordering of any two keys
33	// to change.
34	//
35	// Names starting with "leveldb." are reserved and should not be used
36	// by any users of this package.
37	Name() string
38
39	// Bellow are advanced functions used used to reduce the space requirements
40	// for internal data structures such as index blocks.
41
42	// Separator appends a sequence of bytes x to dst such that a <= x && x < b,
43	// where 'less than' is consistent with Compare. An implementation should
44	// return nil if x equal to a.
45	//
46	// Either contents of a or b should not by any means modified. Doing so
47	// may cause corruption on the internal state.
48	Separator(dst, a, b []byte) []byte
49
50	// Successor appends a sequence of bytes x to dst such that x >= b, where
51	// 'less than' is consistent with Compare. An implementation should return
52	// nil if x equal to b.
53	//
54	// Contents of b should not by any means modified. Doing so may cause
55	// corruption on the internal state.
56	Successor(dst, b []byte) []byte
57}
58