r9e

README

RamStorage (r9e)

RamStorage (r9e) is a Thread-Safe Golang library used for memory storage with convenient methods to store and retrieve data.

This is focused on usability and simplicity rather than performance, but it doesn't mean that it's not fast. Discover it for yourself

Overview

Taking advantage of the Golang Generics and internal golang data structures like Map, RamStorage (r9e) provides a simple way to store and retrieve data.

The goal is to provide a simple and easy way to use a library to store and retrieve data from memory using a simple API and data structures.

Available Containers

• MapKeyValue[K comparable, T any] using sync.RWMutex

Documentation

Official documentation is available on pkg.go.dev -> slashdevops/r9e

Installing

Latest release:

go get -u github.com/slashdevops/r9e@latest

Specific release:

go get -u github.com/slashdevops/r9e@vx.y.z

Adding it to your project:

import "github.com/slashdevops/r9e"

Example

package main

import (
  "fmt"

  "github.com/slashdevops/r9e"
)

func main() {
  type MathematicalConstants struct {
    Name  string
    Value float64
  }

  // With Capacity allocated
  // kv := r9e.NewMapKeyValue[string, MathematicalConstants](r9e.WithCapacity(5))
  kv := r9e.NewMapKeyValue[string, MathematicalConstants]()

  kv.Set("pi", MathematicalConstants{"Archimedes' constant", 3.141592})
  kv.Set("e", MathematicalConstants{"Euler number, Napier's constant", 2.718281})
  kv.Set("γ", MathematicalConstants{"Euler number, Napier's constant", 0.577215})
  kv.Set("Φ", MathematicalConstants{"Golden ratio constant", 1.618033})
  kv.Set("ρ", MathematicalConstants{"Plastic number ρ (or silver constant)", 2.414213})

  kvFilteredValues := kv.FilterValue(func(value MathematicalConstants) bool {
    return value.Value > 2.0
  })

  fmt.Println("Mathematical Constants:")
  kvFilteredValues.ForEach(func(key string, value MathematicalConstants) {
    fmt.Printf("Key: %v, Name: %v, Value: %v\n", key, value.Name, value.Value)
  })

  fmt.Printf("\n")
  fmt.Printf("The most famous mathematical constant:\n")
  fmt.Printf("Name: %v, Value: %v\n", kv.Get("pi").Name, kv.Get("pi").Value)

  lst := kv.SortValues(func(value1, value2 MathematicalConstants) bool {
    return value1.Value > value2.Value
  })

  fmt.Printf("\n")
  fmt.Printf("The most famous mathematical constant sorted by value:\n")
  for i, value := range lst {
    fmt.Printf("i: %v, Name: %v, Value: %v\n", i, value.Name, value.Value)
  }

  kvHigh, kvLow := kv.Partition(func(key string, value MathematicalConstants) bool {
    return value.Value > 2.5
  })

  fmt.Printf("\n")
  fmt.Printf("Mathematical constants which value is greater than 2.5:\n")
  kvHigh.ForEach(func(key string, value MathematicalConstants) {
    fmt.Printf("Key: %v, Name: %v, Value: %v\n", key, value.Name, value.Value)
  })

  fmt.Printf("\n")
  fmt.Printf("Mathematical constants which value is less than 2.5:\n")
  kvLow.ForEach(func(key string, value MathematicalConstants) {
    fmt.Printf("Key: %v, Name: %v, Value: %v\n", key, value.Name, value.Value)
  })
}

Output:

Mathematical Constants:
Key: ρ, Name: Plastic number ρ (or silver constant), Value: 2.414213
Key: e, Name: Euler number, Napier's constant, Value: 2.718281
Key: pi, Name: Archimedes' constant, Value: 3.141592

The most famous mathematical constant:
Name: Archimedes' constant, Value: 3.141592

The most famous mathematical constants sorted by value:
i: 0, Name: Archimedes' constant, Value: 3.141592
i: 1, Name: Euler number, Napier's constant, Value: 2.718281
i: 2, Name: Plastic number ρ (or silver constant), Value: 2.414213
i: 3, Name: Golden ratio constant, Value: 1.618033
i: 4, Name: Euler number, Napier's constant, Value: 0.577215

Mathematical constants which value is greater than 2.5:
Key: pi, Name: Archimedes' constant, Value: 3.141592
Key: e, Name: Euler number, Napier's constant, Value: 2.718281

Mathematical constants which value is less than 2.5:
Key: Φ, Name: Golden ratio constant, Value: 1.618033
Key: ρ, Name: Plastic number ρ (or silver constant), Value: 2.414213
Key: γ, Name: Euler number, Napier's constant, Value: 0.577215

How Fast?

Discover it for yourself:

git clone git@github.com:slashdevops/r9e.git
cd r9e/
make bench

License

RamStorage (r9e) is released under the Apache License Version 2.0:

• http://www.apache.org/licenses/LICENSE-2.0.html

Documentation

Overview

Package r9e provides a collection of memory store containers.

Available Containers

* [MapKeyValue[K comparable, T any]](https://pkg.go.dev/github.com/slashdevops/r9e#MapKeyValue) using sync.RWMutex

Example (Basic)

package main

import (
	"fmt"

	"github.com/slashdevops/r9e"
)

func main() {
	type MathematicalConstants struct {
		Name  string
		Value float64
	}

	// With Capacity allocated
	// kv := r9e.NewMapKeyValue[string, MathematicalConstants](r9e.WithCapacity(5))
	kv := r9e.NewMapKeyValue[string, MathematicalConstants]()

	kv.Set("pi", MathematicalConstants{"Archimedes' constant", 3.141592})
	kv.Set("e", MathematicalConstants{"Euler number, Napier's constant", 2.718281})
	kv.Set("γ", MathematicalConstants{"Euler number, Napier's constant", 0.577215})
	kv.Set("Φ", MathematicalConstants{"Golden ratio constant", 1.618033})
	kv.Set("ρ", MathematicalConstants{"Plastic number ρ (or silver constant)", 2.414213})

	kvFilteredValues := kv.FilterValue(func(value MathematicalConstants) bool {
		return value.Value > 2.0
	})

	fmt.Println("Mathematical Constants:")
	kvFilteredValues.ForEach(func(key string, value MathematicalConstants) {
		fmt.Printf("Key: %v, Name: %v, Value: %v\n", key, value.Name, value.Value)
	})

	fmt.Printf("\n")
	fmt.Printf("The most famous mathematical constant:\n")
	fmt.Printf("Name: %v, Value: %v\n", kv.Get("pi").Name, kv.Get("pi").Value)

	lst := kv.SortValues(func(value1, value2 MathematicalConstants) bool {
		return value1.Value > value2.Value
	})

	fmt.Printf("\n")
	fmt.Printf("The most famous mathematical constant sorted by value:\n")
	for i, value := range lst {
		fmt.Printf("i: %v, Name: %v, Value: %v\n", i, value.Name, value.Value)
	}

	kvHigh, kvLow := kv.Partition(func(key string, value MathematicalConstants) bool {
		return value.Value > 2.5
	})

	fmt.Printf("\n")
	fmt.Printf("Mathematical constants which value is greater than 2.5:\n")
	kvHigh.ForEach(func(key string, value MathematicalConstants) {
		fmt.Printf("Key: %v, Name: %v, Value: %v\n", key, value.Name, value.Value)
	})

	fmt.Printf("\n")
	fmt.Printf("Mathematical constants which value is less than 2.5:\n")
	kvLow.ForEach(func(key string, value MathematicalConstants) {
		fmt.Printf("Key: %v, Name: %v, Value: %v\n", key, value.Name, value.Value)
	})
}

Index

• type MapKeyValue
  • func NewMapKeyValue[K comparable, T any](options ...MapKeyValueOptions) *MapKeyValue[K, T]
  • func (r *MapKeyValue[K, T]) Clear()
  • func (r *MapKeyValue[K, T]) Clone() *MapKeyValue[K, T]
  • func (r *MapKeyValue[K, T]) CloneAndClear() *MapKeyValue[K, T]
  • func (r *MapKeyValue[K, T]) ContainsKey(key K) bool
  • func (r *MapKeyValue[K, T]) ContainsValue(value T) bool
  • func (r *MapKeyValue[K, T]) DeepEqual(kv *MapKeyValue[K, T]) bool
  • func (r *MapKeyValue[K, T]) Delete(key K)
  • func (r *MapKeyValue[K, T]) Filter(fn func(key K, value T) bool) *MapKeyValue[K, T]
  • func (r *MapKeyValue[K, T]) FilterKey(fn func(key K) bool) *MapKeyValue[K, T]
  • func (r *MapKeyValue[K, T]) FilterValue(fn func(value T) bool) *MapKeyValue[K, T]
  • func (r *MapKeyValue[K, T]) ForEach(fn func(key K, value T))
  • func (r *MapKeyValue[K, T]) ForEachKey(fn func(key K))
  • func (r *MapKeyValue[K, T]) ForEachValue(fn func(value T))
  • func (r *MapKeyValue[K, T]) Get(key K) T
  • func (r *MapKeyValue[K, T]) GetAnDelete(key K) (T, bool)
  • func (r *MapKeyValue[K, T]) GetCheck(key K) (T, bool)
  • func (r *MapKeyValue[K, T]) IsEmpty() bool
  • func (r *MapKeyValue[K, T]) IsFull() bool
  • func (r *MapKeyValue[K, T]) Key(key K) K
  • func (r *MapKeyValue[K, T]) Keys() []K
  • func (r *MapKeyValue[K, T]) Map(fn func(key K, value T) (newKey K, newValue T)) *MapKeyValue[K, T]
  • func (r *MapKeyValue[K, T]) MapKey(fn func(key K) K) *MapKeyValue[K, T]
  • func (r *MapKeyValue[K, T]) MapValue(fn func(value T) T) *MapKeyValue[K, T]
  • func (r *MapKeyValue[K, T]) Partition(fn func(key K, value T) bool) (match, others *MapKeyValue[K, T])
  • func (r *MapKeyValue[K, T]) PartitionKey(fn func(key K) bool) (match, others *MapKeyValue[K, T])
  • func (r *MapKeyValue[K, T]) PartitionValue(fn func(value T) bool) (match, others *MapKeyValue[K, T])
  • func (r *MapKeyValue[K, T]) Set(key K, value T)
  • func (r *MapKeyValue[K, T]) Size() int
  • func (r *MapKeyValue[K, T]) SortKeys(sortFn func(key1, key2 K) bool) []*K
  • func (r *MapKeyValue[K, T]) SortValues(sortFn func(value1, value2 T) bool) []*T
  • func (r *MapKeyValue[K, T]) Values() []T
• type MapKeyValueOptions
  • func WithCapacity(size int) MapKeyValueOptions

Examples

• Package (Basic)
• NewMapKeyValue (Int)
• NewMapKeyValue (Struct)

Types

type MapKeyValue

type MapKeyValue[K comparable, T any] struct {
	// contains filtered or unexported fields
}

MapKeyValue is a generic key-value store container that is thread-safe. This use a golang native map data structure as underlying data structure and a mutex to protect the data.

func NewMapKeyValue

func NewMapKeyValue[K comparable, T any](options ...MapKeyValueOptions) *MapKeyValue[K, T]

NewMapKeyValue returns a new MapKeyValue container.

Example (Int)

Using int data types

kv := NewMapKeyValue[int, int]()

kv.Set(1, 8096)
kv.Set(25, 4096)

fmt.Printf("key 1: %v, value 1: %v\nkey 2: %v, value 2: %v", 1, kv.Get(1), 25, kv.Get(25))

Output:

key 1: 1, value 1: 8096
key 2: 25, value 2: 4096

Example (Struct)

Using string as key and struct as value data types.

type testStruct struct {
	Name  string
	value float64
}

MathConstants := NewMapKeyValue[string, testStruct]()

MathConstants.Set("Archimedes", testStruct{"This is Archimedes' Constant (Pi)", 3.1415})
MathConstants.Set("Euler", testStruct{"This is Euler's Number (e)", 2.7182})
MathConstants.Set("Golden Ratio", testStruct{"This is The Golden Ratio", 1.6180})

fmt.Printf("name: %v, value: %v\n", MathConstants.Get("Archimedes").Name, MathConstants.Get("Archimedes").value)

Output:

name: This is Archimedes' Constant (Pi), value: 3.1415

func (*MapKeyValue[K, T]) Clear

func (r *MapKeyValue[K, T]) Clear()

Clear deletes all key-value pairs stored in the container.

func (*MapKeyValue[K, T]) Clone

func (r *MapKeyValue[K, T]) Clone() *MapKeyValue[K, T]

Clone returns a new MapKeyValue with a copy of the underlying data.

func (*MapKeyValue[K, T]) CloneAndClear

func (r *MapKeyValue[K, T]) CloneAndClear() *MapKeyValue[K, T]

CloneAndClear returns a new MapKeyValue with a copy of the underlying data and clears the container.

func (*MapKeyValue[K, T]) ContainsKey

func (r *MapKeyValue[K, T]) ContainsKey(key K) bool

ContainsKey returns true if the key is in the container.

func (*MapKeyValue[K, T]) ContainsValue

func (r *MapKeyValue[K, T]) ContainsValue(value T) bool

ContainsValue returns true if the value is in the container.

func (*MapKeyValue[K, T]) DeepEqual

func (r *MapKeyValue[K, T]) DeepEqual(kv *MapKeyValue[K, T]) bool

DeepEqual returns true if the given kv is deep equal to the MapKeyValue container

func (*MapKeyValue[K, T]) Delete

func (r *MapKeyValue[K, T]) Delete(key K)

Delete deletes the value associated with the key.

func (*MapKeyValue[K, T]) Filter

func (r *MapKeyValue[K, T]) Filter(fn func(key K, value T) bool) *MapKeyValue[K, T]

Filter returns a new MapKeyValue after applying the given function fn to each key-value pair.

func (*MapKeyValue[K, T]) FilterKey

func (r *MapKeyValue[K, T]) FilterKey(fn func(key K) bool) *MapKeyValue[K, T]

FilterKey returns a new MapKeyValue after applying the given function fn to each key.

func (*MapKeyValue[K, T]) FilterValue

func (r *MapKeyValue[K, T]) FilterValue(fn func(value T) bool) *MapKeyValue[K, T]

FilterValue returns a new MapKeyValue after applying the given function fn to each value.

func (*MapKeyValue[K, T]) ForEach

func (r *MapKeyValue[K, T]) ForEach(fn func(key K, value T))

ForEach calls the given function for each key-value pair in the container.

func (*MapKeyValue[K, T]) ForEachKey

func (r *MapKeyValue[K, T]) ForEachKey(fn func(key K))

ForEachKey calls the given function for each key in the container.

func (*MapKeyValue[K, T]) ForEachValue

func (r *MapKeyValue[K, T]) ForEachValue(fn func(value T))

ForEachValue calls the given function for each value in the container.

func (*MapKeyValue[K, T]) Get

func (r *MapKeyValue[K, T]) Get(key K) T

Get returns the value associated with the key.

func (*MapKeyValue[K, T]) GetAnDelete

func (r *MapKeyValue[K, T]) GetAnDelete(key K) (T, bool)

GetAnDelete returns the value associated with the key and delete it if the key exist if the key doesn't exist return the given key value false

func (*MapKeyValue[K, T]) GetCheck

func (r *MapKeyValue[K, T]) GetCheck(key K) (T, bool)

GetCheck returns the value associated with the key if this exist also a boolean value if this exist of not.

func (*MapKeyValue[K, T]) IsEmpty

func (r *MapKeyValue[K, T]) IsEmpty() bool

IsEmpty returns true if the container is empty.

func (*MapKeyValue[K, T]) IsFull

func (r *MapKeyValue[K, T]) IsFull() bool

IsFull returns true if the container has elements.

func (*MapKeyValue[K, T]) Key

func (r *MapKeyValue[K, T]) Key(key K) K

Get returns the key value associated with the key.

func (*MapKeyValue[K, T]) Keys

func (r *MapKeyValue[K, T]) Keys() []K

Keys returns all keys stored in the container.

func (*MapKeyValue[K, T]) Map

func (r *MapKeyValue[K, T]) Map(fn func(key K, value T) (newKey K, newValue T)) *MapKeyValue[K, T]

Map returns a new MapKeyValue after applying the given function fn to each key-value pair.

func (*MapKeyValue[K, T]) MapKey

func (r *MapKeyValue[K, T]) MapKey(fn func(key K) K) *MapKeyValue[K, T]

MapKey returns a new MapKeyValue after applying the given function fn to each key.

func (*MapKeyValue[K, T]) MapValue

func (r *MapKeyValue[K, T]) MapValue(fn func(value T) T) *MapKeyValue[K, T]

MapValue returns a new MapKeyValue after applying the given function fn to each value.

func (*MapKeyValue[K, T]) Partition

func (r *MapKeyValue[K, T]) Partition(fn func(key K, value T) bool) (match, others *MapKeyValue[K, T])

Partition returns two new MapKeyValue. One with all the elements that satisfy the predicate and another with the rest. The predicate is applied to each element.

func (*MapKeyValue[K, T]) PartitionKey

func (r *MapKeyValue[K, T]) PartitionKey(fn func(key K) bool) (match, others *MapKeyValue[K, T])

PartitionKey returns two new MapKeyValue. One with all the elements that satisfy the predicate and another with the rest. The predicate is applied to each key.

func (*MapKeyValue[K, T]) PartitionValue

func (r *MapKeyValue[K, T]) PartitionValue(fn func(value T) bool) (match, others *MapKeyValue[K, T])

PartitionValue returns two new MapKeyValue. One with all the elements that satisfy the predicate and another with the rest. The predicate is applied to each value.

func (*MapKeyValue[K, T]) Set

func (r *MapKeyValue[K, T]) Set(key K, value T)

Set sets the value associated with the key.

func (*MapKeyValue[K, T]) Size

func (r *MapKeyValue[K, T]) Size() int

Size returns the number of key-value pairs stored in the container.

func (*MapKeyValue[K, T]) SortKeys

func (r *MapKeyValue[K, T]) SortKeys(sortFn func(key1, key2 K) bool) []*K

SortKeys returns a []*K (keys) after sorting the keys using the given sortFn function.

func (*MapKeyValue[K, T]) SortValues

func (r *MapKeyValue[K, T]) SortValues(sortFn func(value1, value2 T) bool) []*T

SortValues returns a []*T (values) after sorting the values using given function sortFn.

func (*MapKeyValue[K, T]) Values

func (r *MapKeyValue[K, T]) Values() []T

Values returns all values stored in the container.

type MapKeyValueOptions

type MapKeyValueOptions func(*mapKeyValueOptions)

MapKeyValueOptions are the options for MapKeyValue container.

func WithCapacity

func WithCapacity(size int) MapKeyValueOptions

WithCapacity sets the initial capacity allocation of the MapKeyValue container.