README
¶
Key-value Archive File
Introduction
go-kvfile stores key/value pairs to a file.
It is useful in cases where you need a simple and efficient way to store and retrieve key-value data to a file.
The values are concatenated together at the beginning of the file, followed by a set of length-suffixed entries containing each key and the offset of the associated value, followed by a list of positions of index entries.
The Reader reads values from the kvfile and can search for specific keys using a binary search on the key index:
Get(): Looks up the value for the given key.
ReadTo(): Reads the value for the given key to the writer.
Exists(): Checks if the given key exists in the store.
ReadIndexEntry(): Reads the index entry at the given index.
SearchIndexEntry(): Looks up an index entry for the given key.
GetValuePosition(): Determines the position and length of the value for the key.
ScanPrefix(): iterates over key/value pairs with a prefix.
ScanPrefixKeys(): iterates over key/value pairs with a prefix, returning keys only.
Write() writes the given key-value pairs to the file with the writer. It sorts the key/value pairs by key, writes the values to the file, and builds the index.
License
MIT
Documentation
¶
Index ¶
- Variables
- func Write(writer io.Writer, keys [][]byte, writeValue WriteValueFunc) error
- func WriteIterator(writer io.Writer, keyIterator KeyIteratorFunc, writeValueFunc WriteValueFunc) error
- type FileReaderAt
- type IndexEntry
- func (m *IndexEntry) CloneMessageVT() proto.Message
- func (m *IndexEntry) CloneVT() *IndexEntry
- func (*IndexEntry) Descriptor() ([]byte, []int)deprecated
- func (this *IndexEntry) EqualMessageVT(thatMsg proto.Message) bool
- func (this *IndexEntry) EqualVT(that *IndexEntry) bool
- func (x *IndexEntry) GetKey() []byte
- func (x *IndexEntry) GetOffset() uint64
- func (m *IndexEntry) MarshalToSizedBufferVT(dAtA []byte) (int, error)
- func (m *IndexEntry) MarshalToVT(dAtA []byte) (int, error)
- func (m *IndexEntry) MarshalVT() (dAtA []byte, err error)
- func (*IndexEntry) ProtoMessage()
- func (x *IndexEntry) ProtoReflect() protoreflect.Message
- func (x *IndexEntry) Reset()
- func (m *IndexEntry) SizeVT() (n int)
- func (x *IndexEntry) String() string
- func (m *IndexEntry) UnmarshalVT(dAtA []byte) error
- type KeyIteratorFunc
- type Reader
- func (r *Reader) Exists(key []byte) (bool, error)
- func (r *Reader) Get(key []byte) ([]byte, bool, error)
- func (r *Reader) GetValuePosition(key []byte) (idx, length int64, indexEntry *IndexEntry, indexEntryIdx int, err error)
- func (r *Reader) GetValuePositionWithEntry(indexEntry *IndexEntry, indexEntryIdx int) (idx, length int64, err error)
- func (r *Reader) GetWithEntry(indexEntry *IndexEntry, indexEntryIdx int) ([]byte, error)
- func (r *Reader) ReadIndexEntry(indexEntryIdx uint64) (*IndexEntry, error)
- func (r *Reader) ReadTo(key []byte, to io.Writer) (int, bool, error)
- func (r *Reader) ScanPrefix(prefix []byte, cb func(key, value []byte) error) error
- func (r *Reader) ScanPrefixEntries(prefix []byte, cb func(indexEntry *IndexEntry, indexEntryIdx int) error) error
- func (r *Reader) ScanPrefixKeys(prefix []byte, cb func(key []byte) error) error
- func (r *Reader) SearchIndexEntryWithKey(key []byte) (*IndexEntry, int, error)
- func (r *Reader) SearchIndexEntryWithPrefix(prefix []byte, last bool) (*IndexEntry, int, error)
- func (r *Reader) Size() uint64
- type ReaderAtSeeker
- type WriteValueFunc
Constants ¶
This section is empty.
Variables ¶
var ( ErrInvalidLength = fmt.Errorf("proto: negative length found during unmarshaling") ErrIntOverflow = fmt.Errorf("proto: integer overflow") ErrUnexpectedEndOfGroup = fmt.Errorf("proto: unexpected end of group") )
var File_compressed_kv_file_kv_proto protoreflect.FileDescriptor
Functions ¶
func Write ¶
func Write(writer io.Writer, keys [][]byte, writeValue WriteValueFunc) error
Write writes the given key/value pairs to the store in writer. Serializes and writes the key/value pairs. Note: keys will be sorted by key. Note: keys must not contain duplicate keys. writeValue should write the given value to the writer returning the number of bytes written.
func WriteIterator ¶
func WriteIterator(writer io.Writer, keyIterator KeyIteratorFunc, writeValueFunc WriteValueFunc) error
WriteIterator writes using the given iterator callback. The callback should return one key at a time. The keys MUST be sorted or an error will be returned. Serializes and writes the key/value pairs. Note: keys must not contain duplicate keys.
Types ¶
type FileReaderAt ¶
FileReaderAt is a fs.File that implements ReaderAt.
type IndexEntry ¶
type IndexEntry struct {
// Key is the key of the entry.
Key []byte `protobuf:"bytes,1,opt,name=key,proto3" json:"key,omitempty"`
// Offset is the position of the value in bytes.
Offset uint64 `protobuf:"varint,2,opt,name=offset,proto3" json:"offset,omitempty"`
// contains filtered or unexported fields
}
IndexEntry is an entry in the index. The index is sorted by key.
func (*IndexEntry) CloneMessageVT ¶
func (m *IndexEntry) CloneMessageVT() proto.Message
func (*IndexEntry) CloneVT ¶
func (m *IndexEntry) CloneVT() *IndexEntry
func (*IndexEntry) Descriptor
deprecated
func (*IndexEntry) Descriptor() ([]byte, []int)
Deprecated: Use IndexEntry.ProtoReflect.Descriptor instead.
func (*IndexEntry) EqualMessageVT ¶
func (this *IndexEntry) EqualMessageVT(thatMsg proto.Message) bool
func (*IndexEntry) EqualVT ¶
func (this *IndexEntry) EqualVT(that *IndexEntry) bool
func (*IndexEntry) GetKey ¶
func (x *IndexEntry) GetKey() []byte
func (*IndexEntry) GetOffset ¶
func (x *IndexEntry) GetOffset() uint64
func (*IndexEntry) MarshalToSizedBufferVT ¶
func (m *IndexEntry) MarshalToSizedBufferVT(dAtA []byte) (int, error)
func (*IndexEntry) MarshalToVT ¶
func (m *IndexEntry) MarshalToVT(dAtA []byte) (int, error)
func (*IndexEntry) MarshalVT ¶
func (m *IndexEntry) MarshalVT() (dAtA []byte, err error)
func (*IndexEntry) ProtoMessage ¶
func (*IndexEntry) ProtoMessage()
func (*IndexEntry) ProtoReflect ¶
func (x *IndexEntry) ProtoReflect() protoreflect.Message
func (*IndexEntry) Reset ¶
func (x *IndexEntry) Reset()
func (*IndexEntry) SizeVT ¶
func (m *IndexEntry) SizeVT() (n int)
func (*IndexEntry) String ¶
func (x *IndexEntry) String() string
func (*IndexEntry) UnmarshalVT ¶
func (m *IndexEntry) UnmarshalVT(dAtA []byte) error
type KeyIteratorFunc ¶
WriteIteratorFunc is a function that returns key/value pairs to write. The callback should return one key at a time. Return nil, nil if no keys remain.
type Reader ¶
type Reader struct {
// contains filtered or unexported fields
}
Reader is a key/value file reader.
func BuildReader ¶
BuildReader constructs a new Reader, reading the number of index entries.
func BuildReaderWithFile ¶
func BuildReaderWithFile(f FileReaderAt) (*Reader, error)
BuildReaderWithFile constructs a new Reader with an fs.File.
func BuildReaderWithSeeker ¶
func BuildReaderWithSeeker(rd ReaderAtSeeker) (*Reader, error)
BuildReaderWithSeeker constructs a new Reader with a io.ReaderSeeker reading the file size.
func (*Reader) GetValuePosition ¶
func (r *Reader) GetValuePosition(key []byte) (idx, length int64, indexEntry *IndexEntry, indexEntryIdx int, err error)
GetValuePosition determines the position and length of the value for the key.
Returns -1, 1, nil, -1, nil if not found.
func (*Reader) GetValuePositionWithEntry ¶
func (r *Reader) GetValuePositionWithEntry(indexEntry *IndexEntry, indexEntryIdx int) (idx, length int64, err error)
GetValuePositionWithEntry determines the position and length of the value with an entry.
Returns -1, 1, nil, -1, nil if not found.
func (*Reader) GetWithEntry ¶
func (r *Reader) GetWithEntry(indexEntry *IndexEntry, indexEntryIdx int) ([]byte, error)
GetWithEntry returns the value for the given index entry.
func (*Reader) ReadIndexEntry ¶
func (r *Reader) ReadIndexEntry(indexEntryIdx uint64) (*IndexEntry, error)
ReadIndexEntry reads the index entry at the given index.
func (*Reader) ReadTo ¶
ReadTo reads the value for the given key to the writer.
Returns number of bytes read, found, and any error. Returns 0, false, nil if not found.
func (*Reader) ScanPrefix ¶
ScanPrefix iterates over key/value pairs with a prefix.
func (*Reader) ScanPrefixEntries ¶
func (r *Reader) ScanPrefixEntries(prefix []byte, cb func(indexEntry *IndexEntry, indexEntryIdx int) error) error
ScanPrefixEntries iterates over entries with the given key prefix.
func (*Reader) ScanPrefixKeys ¶
ScanPrefixKeys iterates over keys with a prefix.
func (*Reader) SearchIndexEntryWithKey ¶
func (r *Reader) SearchIndexEntryWithKey(key []byte) (*IndexEntry, int, error)
SearchIndexEntryWithKey looks up an index entry for the given key.
If not found, returns nil, idx, err and idx is the index where the searched element would appear if inserted into the list.
func (*Reader) SearchIndexEntryWithPrefix ¶
SearchIndexEntryWithPrefix returns the entry of the first key with the prefix.
If last is true returns the last element that matches the prefix.
If the key or prefix is not found, returns nil, idx, err, where idx is the element where an element with the given prefix would appear if inserted.
type ReaderAtSeeker ¶
type ReaderAtSeeker interface {
io.ReaderAt
io.ReadSeeker
}
ReaderAtSeeker is a ReaderAt and a ReadSeeker.
Source Files
Directories