Documentation
¶
Overview ¶
Package ffmap provides a flat-file key-value storage library optimized for plain text storage (like in git).
Index ¶
- func SetMapValues[T any](kv MutableFFMap, m map[string]T) error
- func SetSliceValues[T any](kv MutableFFMap, s []T, keyProvider func(value T) string) error
- type EncodingError
- type FFMap
- type KeyValueCSV
- func (kv *KeyValueCSV) Commit() error
- func (kv *KeyValueCSV) ContainsKey(key string) bool
- func (kv *KeyValueCSV) Delete(key string)
- func (kv *KeyValueCSV) DeleteAll()
- func (kv *KeyValueCSV) Get(key string, value interface{}) (bool, error)
- func (kv *KeyValueCSV) KeySet() []string
- func (kv *KeyValueCSV) Set(key string, value interface{}) error
- func (kv *KeyValueCSV) Size() int
- type MutableFFMap
- type TypeMismatchError
- type TypedFFMap
- func (tfm *TypedFFMap[T]) Commit() error
- func (tfm *TypedFFMap[T]) ContainsKey(key string) bool
- func (tfm *TypedFFMap[T]) Delete(key string)
- func (tfm *TypedFFMap[T]) DeleteAll()
- func (tfm *TypedFFMap[T]) Get(key string) (T, bool)
- func (tfm *TypedFFMap[T]) KeySet() []string
- func (tfm *TypedFFMap[T]) Set(key string, value T) error
- func (tfm *TypedFFMap[T]) SetMapValues(m map[string]T) error
- func (tfm *TypedFFMap[T]) SetSliceValues(s []T, keyProvider func(value T) string) error
- func (tfm *TypedFFMap[T]) Size() int
- type ValidationError
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func SetMapValues ¶ added in v0.3.7
func SetMapValues[T any](kv MutableFFMap, m map[string]T) error
SetMapValues iterates the provided map and sets all key-value pairs into the provided MutableFFMap. If errors occur, remaining values are still set and a joined error is returned.
func SetSliceValues ¶ added in v0.3.7
func SetSliceValues[T any](kv MutableFFMap, s []T, keyProvider func(value T) string) error
SetSliceValues iterates the provided slice, using the keyProvider function to derive the key for each element, and sets the values into the provided MutableFFMap. If errors occur, remaining values are still set and a joined error is returned.
Types ¶
type EncodingError ¶ added in v0.3.10
type EncodingError struct {
// Key provides the key being set during the encoding.
Key string
// Value provides the value that failed to encode.
Value interface{}
// Message provides the flat file map context of the failure.
Message string
// Err provides the underlying error if it was sourced from another encoding (e.g. json.Marshal failure).
Err error
}
EncodingError indicates that a value cannot be encoded for storage.
func (*EncodingError) Error ¶ added in v0.3.10
func (e *EncodingError) Error() string
func (*EncodingError) Unwrap ¶ added in v0.3.10
func (e *EncodingError) Unwrap() error
type FFMap ¶ added in v0.3.0
type FFMap interface {
// Size reports how many entries are stored in the map.
Size() int
// Get retrieves the value for the given key into the provided pointer.
// The returned bool indicates if the value was found and matches the type.
// Check the error for possible parsing, or type errors in setting into the provided value.
Get(key string, value interface{}) (bool, error)
// ContainsKey reports whether the map has an associated value with the provided key.
ContainsKey(key string) bool
// KeySet returns all keys stored within the map.
KeySet() []string
}
func OpenReadOnlyCSV ¶
OpenReadOnlyCSV reads a CSV map file, providing a read-only view of the data.
type KeyValueCSV ¶
type KeyValueCSV struct {
// contains filtered or unexported fields
}
KeyValueCSV provides a primarily in-memory key-value map with the ability to load and commit the contents to disk.
func OpenCSV ¶
func OpenCSV(filename string) (*KeyValueCSV, error)
OpenCSV creates or reads an existing CSV map file.
func (*KeyValueCSV) Commit ¶
func (kv *KeyValueCSV) Commit() error
Commit writes the current state of the map to disk.
func (*KeyValueCSV) ContainsKey ¶
func (kv *KeyValueCSV) ContainsKey(key string) bool
ContainsKey reports whether the given key exists in the map.
func (*KeyValueCSV) Delete ¶
func (kv *KeyValueCSV) Delete(key string)
Delete removes the key from the map if it exists.
func (*KeyValueCSV) DeleteAll ¶ added in v0.3.1
func (kv *KeyValueCSV) DeleteAll()
DeleteAll removes all entries from the map.
func (*KeyValueCSV) Get ¶
func (kv *KeyValueCSV) Get(key string, value interface{}) (bool, error)
Get retrieves the value for the given key into the provided pointer. The returned bool indicates whether the key was found. A returned error indicates a failure to set into the provided value.
func (*KeyValueCSV) KeySet ¶
func (kv *KeyValueCSV) KeySet() []string
KeySet returns all keys stored in the map.
func (*KeyValueCSV) Set ¶
func (kv *KeyValueCSV) Set(key string, value interface{}) error
Set stores the provided value under the given key, replacing any existing entry.
func (*KeyValueCSV) Size ¶
func (kv *KeyValueCSV) Size() int
Size returns the number of key-value pairs stored in the map.
type MutableFFMap ¶ added in v0.3.0
type MutableFFMap interface {
FFMap
// Set stores the provided value in the map. When retrieved, the same type must be used.
// If a value already exists, it will be replaced with the new value.
Set(key string, value interface{}) error
// Delete removes the key from the map if present.
Delete(key string)
// DeleteAll will clear or remove all entries from the map.
DeleteAll()
// Commit updates the disk representation to match the in-memory state.
// If this is not invoked, the disk will never be updated.
// The operation may be slow as the file format is optimized.
Commit() error
}
func NewMemoryMap ¶ added in v0.3.10
func NewMemoryMap() MutableFFMap
NewMemoryMap creates a new in-memory map. This map behaves the same as persistent maps, however Commit is a no-op. This is most useful for testing when persistence is not desired.
type TypeMismatchError ¶ added in v0.3.10
type TypeMismatchError struct {
// Key provides the key being retrieved.
Key string
// Message provides the context of the failure.
Message string
}
TypeMismatchError indicates type conversion issues (including overflow).
func (*TypeMismatchError) Error ¶ added in v0.3.10
func (e *TypeMismatchError) Error() string
type TypedFFMap ¶ added in v0.3.0
type TypedFFMap[T any] struct { // contains filtered or unexported fields }
TypedFFMap provides a type-safe wrapper around MutableFFMap that operates on a single value type.
func NewTypedFFMap ¶ added in v0.3.0
func NewTypedFFMap[T any](ffm MutableFFMap) *TypedFFMap[T]
NewTypedFFMap creates a TypedFFMap that operates only with the specified generic value type. If the underlying map contains values of other types, they will apear absent when attempting to retrieve them.
func (*TypedFFMap[T]) Commit ¶ added in v0.3.0
func (tfm *TypedFFMap[T]) Commit() error
Commit will update the disk representation to match the in-memory state. If this is not invoked the disk will never be updated. The operation may be slow as the file format is optimized.
func (*TypedFFMap[T]) ContainsKey ¶ added in v0.3.0
func (tfm *TypedFFMap[T]) ContainsKey(key string) bool
ContainsKey will return true if the map has an associated value with the provided key.
func (*TypedFFMap[T]) Delete ¶ added in v0.3.0
func (tfm *TypedFFMap[T]) Delete(key string)
Delete will remove the key from the map (if present).
func (*TypedFFMap[T]) DeleteAll ¶ added in v0.3.1
func (tfm *TypedFFMap[T]) DeleteAll()
DeleteAll will clear or delete all entries from the map.
func (*TypedFFMap[T]) Get ¶ added in v0.3.0
func (tfm *TypedFFMap[T]) Get(key string) (T, bool)
Get retrieves the value for the given key. The returned bool indicates if the value was found and matches the generic type.
func (*TypedFFMap[T]) KeySet ¶ added in v0.3.0
func (tfm *TypedFFMap[T]) KeySet() []string
KeySet will return all the keys stored within the map.
func (*TypedFFMap[T]) Set ¶ added in v0.3.0
func (tfm *TypedFFMap[T]) Set(key string, value T) error
Set stores the provided value into the map. If a value already exists, it will be replaced with the new value.
func (*TypedFFMap[T]) SetMapValues ¶ added in v0.3.7
func (tfm *TypedFFMap[T]) SetMapValues(m map[string]T) error
SetMapValues iterates the provided map and sets all key-value pairs into the TypedFFMap. If errors occur, remaining values are still set and a joined error is returned.
func (*TypedFFMap[T]) SetSliceValues ¶ added in v0.3.7
func (tfm *TypedFFMap[T]) SetSliceValues(s []T, keyProvider func(value T) string) error
SetSliceValues iterates the provided slice, using the keyProvider function to derive the key for each element, and sets the values into the TypedFFMap. If errors occur, remaining values are still set and a joined error is returned.
func (*TypedFFMap[T]) Size ¶ added in v0.3.0
func (tfm *TypedFFMap[T]) Size() int
Size reports how many entries are stored in the map.
type ValidationError ¶ added in v0.3.10
type ValidationError struct {
// Message provides the context of the failure.
Message string
// Err provides the underlying error if any.
Err error
}
ValidationError indicates invalid input parameters or file format.
func (*ValidationError) Error ¶ added in v0.3.10
func (e *ValidationError) Error() string
func (*ValidationError) Unwrap ¶ added in v0.3.10
func (e *ValidationError) Unwrap() error
Source Files