1// Copyright (c) 2011 The LevelDB Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file. See the AUTHORS file for names of contributors.
4
5#ifndef STORAGE_LEVELDB_INCLUDE_COMPARATOR_H_
6#define STORAGE_LEVELDB_INCLUDE_COMPARATOR_H_
7
8#include <string>
9
10#include "leveldb/export.h"
11
12namespace leveldb {
13
14class Slice;
15
16// A Comparator object provides a total order across slices that are
17// used as keys in an sstable or a database. A Comparator implementation
18// must be thread-safe since leveldb may invoke its methods concurrently
19// from multiple threads.
20class LEVELDB_EXPORT Comparator {
21 public:
22 virtual ~Comparator();
23
24 // Three-way comparison. Returns value:
25 // < 0 iff "a" < "b",
26 // == 0 iff "a" == "b",
27 // > 0 iff "a" > "b"
28 virtual int Compare(const Slice& a, const Slice& b) const = 0;
29
30 // The name of the comparator. Used to check for comparator
31 // mismatches (i.e., a DB created with one comparator is
32 // accessed using a different comparator.
33 //
34 // The client of this package should switch to a new name whenever
35 // the comparator implementation changes in a way that will cause
36 // the relative ordering of any two keys to change.
37 //
38 // Names starting with "leveldb." are reserved and should not be used
39 // by any clients of this package.
40 virtual const char* Name() const = 0;
41
42 // Advanced functions: these are used to reduce the space requirements
43 // for internal data structures like index blocks.
44
45 // If *start < limit, changes *start to a short string in [start,limit).
46 // Simple comparator implementations may return with *start unchanged,
47 // i.e., an implementation of this method that does nothing is correct.
48 virtual void FindShortestSeparator(std::string* start,
49 const Slice& limit) const = 0;
50
51 // Changes *key to a short string >= *key.
52 // Simple comparator implementations may return with *key unchanged,
53 // i.e., an implementation of this method that does nothing is correct.
54 virtual void FindShortSuccessor(std::string* key) const = 0;
55};
56
57// Return a builtin comparator that uses lexicographic byte-wise
58// ordering. The result remains the property of this module and
59// must not be deleted.
60LEVELDB_EXPORT const Comparator* BytewiseComparator();
61
62} // namespace leveldb
63
64#endif // STORAGE_LEVELDB_INCLUDE_COMPARATOR_H_
65