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 
12 namespace leveldb {
13 
14 class 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.
20 class 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.
60 LEVELDB_EXPORT const Comparator* BytewiseComparator();
61 
62 }  // namespace leveldb
63 
64 #endif  // STORAGE_LEVELDB_INCLUDE_COMPARATOR_H_
65