safeorderedmap

README

****# Safe Ordered Map

Overview

Safe Ordered Map is a thread-safe, ordered map implementation for Go, which maintains the insertion order while providing safe concurrent access. It is a generic implementation that accepts keys as strings and values of any type.

Features

• Thread-safe: Safe concurrent access with read-write mutexes for synchronization.
• Ordered: Maintains the insertion order, allowing ordered iterations.
• Generics: Supports any value type, thanks to Go generics.
• JSON Serialization: Implements MarshalJSON and UnmarshalJSON for easy JSON serialization and deserialization.
• Rich Functional API: Provides a collection of functional methods for easy manipulation of map elements.

Table for the CRUD Operations

Method	Description	Input	Output
Set	Sets a value in the map.	Key (string), Value (T)	None
Get	Gets a value from the map.	Key (string)	Value (T)
GetByIndex	GetByIndex a value from the map based on the index.	Index (int)	Value (T)
Delete	Deletes a value from the map.	Key (string)	None
First	First return the first element of the map.	None	Value (T)
Last	Last return the last element of the map.	None	Value (T)

Table for the Operations on Keys and Values

Method	Description	Input	Output
Keys	Returns a list of all keys.	None	List of keys (strings)
Values	Returns a list of all values in the same order as the keys.	None	List of values (T)

Table for the Meta Operations

Method	Description	Input	Output
Size	Returns the number of elements in the map.	None	Number of elements (int)
Empty	Checks if the map is empty and returns a boolean value.	None	Boolean (true if map is empty)
Clone	Creates a deep copy of the map and returns it.	None	New SafeOrderedMap with same elements
Index	Returns the index and value of the given key.	Key	Index (int), Value (T), bool (true if key exists)

Table Regarding Collection Operations (Higher-Order Functions)

Method	Description	Input	Output	Modifies Original Map
All	Checks if all elements in the map satisfy a given condition (predicate) and returns a boolean value.	Predicate (key, value)	Boolean (true if all meet condition)	No
Map	Applies a given function to all elements in the map and creates a new map containing the results.	Function (key, value)	New map with transformed elements	No
Filter	Creates a new map containing only the elements that satisfy a given condition (predicate).	Predicate (key, value)	New map with filtered elements	No
Each	Iterates over all elements and applies a given function to each element without returning any result.	Function (key, value)	None	No
Reduce	Accumulates the elements in the map using a given binary function.	Binary function, initial value	Accumulated single value	No
Find	Returns the first element that satisfies a given predicate.	Predicate (key, value)	Key, value, boolean (true if found)	No
Any	Checks if any element in the map satisfies a given predicate.	Predicate (key, value)	Boolean (true if any element meets condition)	No
TakeWhile	Returns a new ordered map containing the longest prefix of elements that satisfy a given predicate.	Predicate (key, value)	New map with elements that meet condition	No
DropWhile	Returns a new ordered map with all elements after (and not including) the first element that does not satisfy a given predicate.	Predicate (key, value)	New map with elements after not meeting condition	No

Table Regarding Set Operations

Method	Description	Input	Output
Union	Returns a new map containing all elements present in the original map and the other map.	Another ordered map	New map with all elements from both maps
Difference	Returns a new map containing elements present in the original map but not in the other map.	Another ordered map	New map with elements present in original but not other
Subset	Checks if all elements in the map are present in the other map.	Another ordered map	Boolean (true if all elements are present in other)
Superset	Checks if all elements in the other map are present in the map.	Another ordered map	Boolean (true if all elements are present in map)

These set operations provide a powerful way to compare and combine the elements of two ordered maps, allowing developers to easily manipulate and transform data.

Installation

Use go get to add the safeorderedmap package to your project:

go get github.com/thalesfsp/go-common-types/safeorderedmap

Usage

Example:

package main

import (
	"fmt"
	"github.com/thalesfsp/go-common-types/safeorderedmap"
)

func main() {
	som := safeorderedmap.New[int]()
	som.Set("one", 1)
	som.Set("two", 2)
	som.Set("three", 3)

	somProcessed := som.Each(func(k string, e int) {e * 2})

	fmt.Println(somProcessed) // {one: 2, two: 4, three: 6}
}

License

See LICENSE file for more details.

Contributing

Feel free to open issues or submit pull requests with improvements or bug fixes. Please ensure that your code follows the coding standards

Documentation

Index

• type SafeOrderedMap
  • func New[T any]() *SafeOrderedMap[T]
  • func (m *SafeOrderedMap[T]) Add(key string, value T) *SafeOrderedMap[T]
  • func (m *SafeOrderedMap[T]) All(predicate func(key string, value T) bool) bool
  • func (m *SafeOrderedMap[T]) Any(predicate func(key string, value T) bool) bool
  • func (m *SafeOrderedMap[T]) Clone() *SafeOrderedMap[T]
  • func (m *SafeOrderedMap[T]) Contains(key string) bool
  • func (m *SafeOrderedMap[T]) Delete(key string) *SafeOrderedMap[T]
  • func (m *SafeOrderedMap[T]) Difference(other *SafeOrderedMap[T]) *SafeOrderedMap[T]
  • func (m *SafeOrderedMap[T]) DropWhile(predicate func(key string, value T) bool) *SafeOrderedMap[T]
  • func (m *SafeOrderedMap[T]) Each(f func(key string, value T)) *SafeOrderedMap[T]
  • func (m *SafeOrderedMap[T]) Empty() bool
  • func (m *SafeOrderedMap[T]) Filter(predicate func(key string, value T) bool) *SafeOrderedMap[T]
  • func (m *SafeOrderedMap[T]) Find(predicate func(key string, value T) bool) (string, T, bool)
  • func (m *SafeOrderedMap[T]) First() (string, T, bool)
  • func (m *SafeOrderedMap[T]) Get(key string) (T, bool)
  • func (m *SafeOrderedMap[T]) GetByIndex(i int) (T, bool)
  • func (m *SafeOrderedMap[T]) Index(key string) (int, T, bool)
  • func (m *SafeOrderedMap[T]) Intersection(other *SafeOrderedMap[T]) *SafeOrderedMap[T]
  • func (m *SafeOrderedMap[T]) Keys() []string
  • func (m *SafeOrderedMap[T]) Last() (string, T, bool)
  • func (m *SafeOrderedMap[T]) Map(f func(key string, value T) T) *SafeOrderedMap[T]
  • func (m *SafeOrderedMap[T]) MarshalBSON() ([]byte, error)
  • func (m *SafeOrderedMap[T]) MarshalJSON() ([]byte, error)
  • func (m *SafeOrderedMap[T]) Reduce(reducer func(accum T, key string, value T) T, initial T) T
  • func (m *SafeOrderedMap[T]) Size() int
  • func (m *SafeOrderedMap[T]) String() string
  • func (m *SafeOrderedMap[T]) Subset(other *SafeOrderedMap[T]) bool
  • func (m *SafeOrderedMap[T]) Superset(other *SafeOrderedMap[T]) bool
  • func (m *SafeOrderedMap[T]) TakeWhile(predicate func(key string, value T) bool) *SafeOrderedMap[T]
  • func (m *SafeOrderedMap[T]) Union(other *SafeOrderedMap[T]) *SafeOrderedMap[T]
  • func (m *SafeOrderedMap[T]) UnmarshalBSON(data []byte) error
  • func (m *SafeOrderedMap[T]) UnmarshalJSON(data []byte) error
  • func (m *SafeOrderedMap[T]) Values() []T

Types

type SafeOrderedMap

type SafeOrderedMap[T any] struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

SafeOrderedMap is a map that preserves the order of keys powered by generics.

func New

func New[T any]() *SafeOrderedMap[T]

New creates a new Safe Ordered Map.

func (*SafeOrderedMap[T]) Add

func (m *SafeOrderedMap[T]) Add(key string, value T) *SafeOrderedMap[T]

Add a value in the map.

func (*SafeOrderedMap[T]) All

func (m *SafeOrderedMap[T]) All(predicate func(key string, value T) bool) bool

All checks if all elements in the map satisfy the predicate.

This method checks if all elements in the map satisfy a given condition (predicate). It returns a boolean value, which is true if all elements meet the condition, and false otherwise. The All method stops processing as soon as it finds an element that does not satisfy the condition.

func (*SafeOrderedMap[T]) Any

func (m *SafeOrderedMap[T]) Any(predicate func(key string, value T) bool) bool

Any checks if any element in the map satisfies the given predicate.

Iterates over the map and checks if any element satisfies a given predicate. It takes a predicate (a function that returns a boolean) as input. If any element satisfies the predicate, it returns true. If no element satisfies the predicate, it returns false.

func (*SafeOrderedMap[T]) Clone

func (m *SafeOrderedMap[T]) Clone() *SafeOrderedMap[T]

Clone creates a deep copy of the map and returns it.

func (*SafeOrderedMap[T]) Contains

func (m *SafeOrderedMap[T]) Contains(key string) bool

Contains checks if the set contains a given element.

func (*SafeOrderedMap[T]) Delete

func (m *SafeOrderedMap[T]) Delete(key string) *SafeOrderedMap[T]

Delete a value from the map.

func (*SafeOrderedMap[T]) Difference

func (m *SafeOrderedMap[T]) Difference(other *SafeOrderedMap[T]) *SafeOrderedMap[T]

Difference returns a new ordered map containing elements present in the original map but not in the other map.

func (*SafeOrderedMap[T]) DropWhile

func (m *SafeOrderedMap[T]) DropWhile(predicate func(key string, value T) bool) *SafeOrderedMap[T]

DropWhile returns a new ordered map with all elements after (and not including) the first element that does not satisfy the given predicate.

Iterates over the map and returns a new ordered map with all elements after (and not including) the first element that does not satisfy a given predicate. It takes a predicate (a function that returns a boolean) as input. The method iterates over the elements in the map and starts adding elements to the resulting map once an element that does not satisfy the predicate is encountered.

func (*SafeOrderedMap[T]) Each

func (m *SafeOrderedMap[T]) Each(f func(key string, value T)) *SafeOrderedMap[T]

Each iterates over the map and calls the given function for each key-value pair.

This method iterates over all elements in the map and applies a given function to each element. The function can perform any operation, such as printing or modifying the elements. However, the Each method itself does not return any result.

func (*SafeOrderedMap[T]) Empty

func (m *SafeOrderedMap[T]) Empty() bool

Empty checks if the map is empty and returns a boolean value.

func (*SafeOrderedMap[T]) Filter

func (m *SafeOrderedMap[T]) Filter(predicate func(key string, value T) bool) *SafeOrderedMap[T]

Filter filters elements in the map based on the predicate and returns a new ordered map containing only elements that satisfy the predicate.

This method creates a new map containing only the elements that satisfy a given condition (predicate). The original map remains unchanged. The new map maintains the insertion order of the original map.

func (*SafeOrderedMap[T]) Find

func (m *SafeOrderedMap[T]) Find(predicate func(key string, value T) bool) (string, T, bool)

Find returns the first element that satisfies the given predicate.

Iterates over the map and returns the first element that satisfies a given predicate. It takes a predicate (a function that returns a boolean) as input. If there is an element that satisfies the predicate, it returns that element along with the corresponding key and a boolean value true. If no element satisfies the predicate, it returns a zero value for the type, an empty string for the key, and false for the boolean value.

func (*SafeOrderedMap[T]) First

func (m *SafeOrderedMap[T]) First() (string, T, bool)

First return the first element of the map.

func (*SafeOrderedMap[T]) Get

func (m *SafeOrderedMap[T]) Get(key string) (T, bool)

Get a value from the map.

func (*SafeOrderedMap[T]) GetByIndex

func (m *SafeOrderedMap[T]) GetByIndex(i int) (T, bool)

GetByIndex a value from the map based on the index.

func (*SafeOrderedMap[T]) Index

func (m *SafeOrderedMap[T]) Index(key string) (int, T, bool)

Index returns the index and value of the given key.

func (*SafeOrderedMap[T]) Intersection

func (m *SafeOrderedMap[T]) Intersection(other *SafeOrderedMap[T]) *SafeOrderedMap[T]

Intersection returns a new ordered map containing elements present in both maps.

func (*SafeOrderedMap[T]) Keys

func (m *SafeOrderedMap[T]) Keys() []string

Keys returns a list of all keys.

func (*SafeOrderedMap[T]) Last

func (m *SafeOrderedMap[T]) Last() (string, T, bool)

Last return the last element of the map.

func (*SafeOrderedMap[T]) Map

func (m *SafeOrderedMap[T]) Map(f func(key string, value T) T) *SafeOrderedMap[T]

Map applies the function f to all elements in the map and returns a new ordered map with the results.

This method applies a given function to all elements in the map and creates a new map containing the results. The original map remains unchanged. The new map maintains the insertion order of the original map.

func (*SafeOrderedMap[T]) MarshalBSON

func (m *SafeOrderedMap[T]) MarshalBSON() ([]byte, error)

MarshalBSON implements bson.Marshaler interface for SafeOrderedMap.

func (*SafeOrderedMap[T]) MarshalJSON

func (m *SafeOrderedMap[T]) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler interface for SafeOrderedMap.

func (*SafeOrderedMap[T]) Reduce

func (m *SafeOrderedMap[T]) Reduce(reducer func(accum T, key string, value T) T, initial T) T

Reduce accumulates the elements in the map using the given binary function.

Iterates over the map and accumulates the elements using a given binary function. It takes a binary function (a function that accepts two arguments) and an initial value as input. The method applies the function to the initial value and the first element, then to the result and the next element, and so on, until all elements in the map have been processed. The final result is a single accumulated value.

func (*SafeOrderedMap[T]) Size

func (m *SafeOrderedMap[T]) Size() int

Size returns the number of elements in the map.

func (*SafeOrderedMap[T]) String

func (m *SafeOrderedMap[T]) String() string

String is the stringer implementation.

func (*SafeOrderedMap[T]) Subset

func (m *SafeOrderedMap[T]) Subset(other *SafeOrderedMap[T]) bool

Subset checks if all elements of the original map are present in the other map.

func (*SafeOrderedMap[T]) Superset

func (m *SafeOrderedMap[T]) Superset(other *SafeOrderedMap[T]) bool

Superset checks if all elements of the other map are present in the original map.

func (*SafeOrderedMap[T]) TakeWhile

func (m *SafeOrderedMap[T]) TakeWhile(predicate func(key string, value T) bool) *SafeOrderedMap[T]

TakeWhile returns a new ordered map containing the longest prefix of elements that satisfy the given predicate.

Iterates over the map and returns a new ordered map containing the longest prefix of elements that satisfy a given predicate. It takes a predicate (a function that returns a boolean) as input. If an element satisfies the predicate, it is added to the resulting map. The process stops once an element that does not satisfy the predicate is encountered.

func (*SafeOrderedMap[T]) Union

func (m *SafeOrderedMap[T]) Union(other *SafeOrderedMap[T]) *SafeOrderedMap[T]

Union returns a new ordered map containing all unique elements from both maps. The order of elements in the resulting map will be based on the order of elements in the original maps.

func (*SafeOrderedMap[T]) UnmarshalBSON

func (m *SafeOrderedMap[T]) UnmarshalBSON(data []byte) error

UnmarshalBSON implements bson.Unmarshaler interface for SafeOrderedMap.

func (*SafeOrderedMap[T]) UnmarshalJSON

func (m *SafeOrderedMap[T]) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler interface for SafeOrderedMap.

func (*SafeOrderedMap[T]) Values

func (m *SafeOrderedMap[T]) Values() []T

Values returns a list of all values.