gomap

README

Gomap

Gomap is a generic map implementation in Go, supporting dynamic key-value pairs of any data type. It offers essential operations like adding, deleting, and checking for key-value pairs, along with advanced functionalities such as iteration, merging, intersection, and conditional mapping. Its flexibility allows seamless manipulation and querying, making it a powerful tool for various applications.

Features

🔑 Key Operations

Effortlessly manage key-value pairs by adding, deleting, and replacing them. Employ custom functions to pop values and make replacements seamlessly.

🔍 Query Operations

Determine key existence, retrieve corresponding values, and identify specific values within the hash table

🔄 Iteration

Navigate through keys and values smoothly, applying functions and breaking based on specified conditions.

🔗 Set Operations

Effortlessly compute intersections with other hash tables. Merge hash tables with ease and apply custom merging functions to create cohesive datasets.

🎛️ Functional Operations

Filter data based on conditions and map values efficiently using custom functions. Compare hash tables for equality or define your own custom equality functions to ensure accurate results.

🛠️ Convenience Functions

Retrieve keys or values as slices for easy handling. Quickly check hash table emptiness, presence, and retrieve its length.

Installation

You can install it in your Go project using go get:

go get github.com/lindsaygelle/gomap

Usage

Import the package into your Go code:

import (
	"github.com/lindsaygelle/gomap"
)

Methods

Provided methods for &gomap.Map[K]V.

Add

Adds a key-value pair to the hash table and returns the updated hash table.

myMap := &gomap.Map[string, int]{}
myMap.Add("key1", 1)
myMap.Add("key2", 2)
fmt.Println(myMap) // &map[key1:1 key2:2]

AddLength

Adds a key-value pair to the hash table and returns the new length of the hash table.

myMap := &gomap.Map[string, int]{}
length := myMap.AddLength("key1", 1)
fmt.Println(length) // 1

AddMany

Adds multiple key-value pairs to the hash table and returns the updated hash table.

myMap := &gomap.Map[string, int]{}
myMap.AddMany(map[string]int{"key1": 1, "key2": 2})
fmt.Println(myMap) // &map[key1:1 key2:2]

AddManyFunc

Adds key-value pairs from a slice of maps to the hash table using a custom function and returns the updated hash table.

myMap := &gomap.Map[string, int]{}
myMaps := []map[string]int{{"key1": 1}, {"key2": 2}}
myMap.AddManyFunc(myMaps, func(i int, key string, value int) bool {
    return true // Add all key-value pairs
})
fmt.Println(myMap) // &map[key1:1 key2:2]

AddManyOK

Adds multiple key-value pairs to the hash table and returns a slice indicating successful additions.

myMap := &gomap.Map[string, int]{}
results := myMap.AddManyOK(map[string]int{"key1": 1, "key2": 2})
fmt.Println(results) // &[true, true]

AddOK

Adds a key-value pair to the hash table and returns true if the addition was successful, false otherwise.

myMap := &gomap.Map[string, int]{}
added := myMap.AddOK("key1", 1)
fmt.Println(added) // true

Contains

Checks if the given value is present in the hash table and returns the corresponding key along with a boolean indicating existence.

myMap := &gomap.Map[string, int]{"key1": 1, "key2": 2}
key, exists := myMap.Contains(2)
fmt.Println(key, exists) // key2 true

Delete

Removes the specified key and its associated value from the hash table and returns the updated hash table.

myMap := &gomap.Map[string, int]{"key1": 1, "key2": 2}
myMap.Delete("key1")
fmt.Println(myMap) // &map[key2:2]

DeleteLength

Removes the specified key and its associated value from the hash table and returns the new length of the hash table.

myMap := &gomap.Map[string, int]{"key1": 1, "key2": 2}
length := myMap.DeleteLength("key1")
fmt.Println(length) // 1

DeleteMany

Removes multiple keys and their associated values from the hash table and returns the updated hash table.

myMap := &gomap.Map[string, int]{"key1": 1, "key2": 2}
myMap.DeleteMany("key1", "key2")
fmt.Println(myMap) // &map[]

DeleteManyFunc

Removes key-value pairs from the hash table using a custom function and returns the updated hash table.

myMap := &gomap.Map[string, int]{"key1": 1, "key2": 2}
myMap.DeleteManyFunc(func(key string, value int) bool {
    return key == "key1"
})
fmt.Println(myMap) // &map[key2:2]

DeleteManyOK

Removes multiple keys and their associated values from the hash table and returns a slice indicating successful deletions.

myMap := &gomap.Map[string, int]{"key1": 1, "key2": 2}
results := myMap.DeleteManyOK("key1", "key2")
fmt.Println(results) // &[true, true]

DeleteManyValues

Removes multiple values from the hash table and returns the updated hash table.

myMap := &gomap.Map[string, int]{"key1": 1, "key2": 2}
myMap.DeleteManyValues(1, 2)
fmt.Println(myMap) // &map[]

DeleteOK

Removes the specified key and its associated value from the hash table and returns true if the deletion was successful, false otherwise.

myMap := &gomap.Map[string, int]{"key1": 1, "key2": 2}
deleted := myMap.DeleteOK("key1")
fmt.Println(deleted) // true

Each

Applies the given function to each key-value pair in the hash table.

myMap := &gomap.Map[string, int]{"key1": 1, "key2": 2}
myMap.Each(func(key string, value int) {
    fmt.Println(key, value)
})
// Output:
// key1 1
// key2 2

EachBreak

Applies the given function to each key-value pair in the hash table and breaks the iteration if the function returns false.

myMap := &gomap.Map[string, int]{"key1": 1, "key2": 2}
myMap.EachBreak(func(key string, value int) bool {
    fmt.Println(key, value)
    return key != "key1"
})
// Output:
// key1 1

EachKey

Applies the given function to each key in the hash table.

myMap := &gomap.Map[string, int]{"key1": 1, "key2": 2}
myMap.EachKey(func(key string) {
    fmt.Println(key)
})
// Output:
// key1
// key2

EachKeyBreak

Applies the given function to each key in the hash table and breaks the iteration if the function returns false.

myMap := &gomap.Map[string, int]{"key1": 1, "key2": 2}
myMap.EachKeyBreak(func(key string) bool {
    fmt.Println(key)
    return key != "key1"
})
// Output:
// key1

EachValue

Applies the given function to each value in the hash table.

myMap := &gomap.Map[string, int]{"key1": 1, "key2": 2}
myMap.EachValue(func(value int) {
    fmt.Println(value)
})
// Output:
// 1
// 2

EachValueBreak

Applies the given function to each value in the hash table and breaks the iteration if the function returns false.

myMap := &gomap.Map[string, int]{"key1": 1, "key2": 2}
myMap.EachValueBreak(func(value int) bool {
    fmt.Println(value)
    return value != 1
})
// Output:
// 1

EmptyInto

Empties the current hash table and inserts its content into another hash table. It returns the updated destination hash table.

source := &gomap.Map[string, int]{"key1": 1, "key2": 2}
destination := &gomap.Map[string, int]{"key3": 3}
destination = source.EmptyInto(destination)
fmt.Println(destination) // &map[key1:1 key2:2]

Equal

Checks if the current hash table is equal to another hash table.

myMap1 := &gomap.Map[string, int]{"key1": 1, "key2": 2}
myMap2 := &gomap.Map[string, int]{"key1": 1, "key2": 2}
isEqual := myMap1.Equal(myMap2)
fmt.Println(isEqual) // true

EqualFunc

Checks if the current hash table is equal to another hash table using a custom comparison function.

myMap1 := &gomap.Map[string, int]{"key1": 1, "key2": 2}
myMap2 := &gomap.Map[string, int]{"key1": 1, "key2": 4}
isEqual := myMap1.EqualFunc(myMap2, func(a int, b int) bool {
    return a == b || a%2 == 0 && b%2 == 0
})
fmt.Println(isEqual) // true (custom comparison allows for even values)

EqualLength

Checks if the current hash table is equal in length to another hash table.

myMap1 := &gomap.Map[string, int]{"key1": 1, "key2": 2}
myMap2 := &gomap.Map[string, int]{"key1": 1, "key2": 2, "key3": 3}
isEqualLength := myMap1.EqualLength(myMap2)
fmt.Println(isEqualLength) // false (different lengths)

Fetch

Retrieves the value associated with the given key from the hash table.

myMap := &gomap.Map[string, int]{"key1": 1, "key2": 2}
value := myMap.Fetch("key1")
fmt.Println(value) // 1

Filter

Applies the given function to each key-value pair in the hash table and retains pairs for which the function returns true.

myMap := &gomap.Map[string, int]{"key1": 1, "key2": 2, "key3": 3}
filteredHashtable := myMap.Filter(func(key string, value int) bool {
    return value%2 == 0
})
fmt.Println(filteredHashtable) // &map[key2:2]

Get

Retrieves the value associated with the given key from the hash table and returns it along with a boolean indicating existence.

myMap := &gomap.Map[string, int]{"key1": 1, "key2": 2}
value, exists := myMap.Get("key2")
fmt.Println(value, exists) // 2 true

GetMany

Retrieves values associated with multiple keys from the hash table and returns them in a slice.

myMap := &gomap.Map[string, int]{"key1": 1, "key2": 2, "key3": 3}
values := myMap.GetMany("key1", "key3")
fmt.Println(values) // &[1 3]

Has

Checks if the given key is present in the hash table.

myMap := &gomap.Map[string, int]{"key1": 1, "key2": 2}
exists := myMap.Has("key1")
fmt.Println(exists) // true

HasMany

Checks if multiple keys are present in the hash table and returns a slice indicating their existence.

myMap := &gomap.Map[string, int]{"key1": 1, "key2": 2, "key3": 3}
exists := myMap.HasMany("key1", "key4")
fmt.Println(exists) // &[true false]

Intersection

Returns a new hash table containing key-value pairs that are present in both the current and another hash table.

myMap1 := &gomap.Map[string, int]{"key1": 1, "key2": 2}
myMap2 := &gomap.Map[string, int]{"key1": 1, "key3": 3}
intersection := myMap1.Intersection(myMap2)
fmt.Println(intersection) // &map[key1:1]

IntersectionFunc

Returns a new hash table containing key-value pairs that are present in both the current and another hash table, determined by a custom function.

myMap1 := &gomap.Map[string, int]{"key1": 1, "key2": 2}
myMap2 := &gomap.Map[string, int]{"key1": 1, "key3": 3}
intersection := myMap1.IntersectionFunc(myMap2, func(key string, a int, b int) bool {
    return a == b
})
fmt.Println(intersection) // &map[key1:1]

IsEmpty

Checks if the hash table is empty.

myMap := &gomap.Map[string, int]{}
isEmpty := myMap.IsEmpty()
fmt.Println(isEmpty) // true

IsPopulated

Checks if the hash table contains key-value pairs.

myMap := &gomap.Map[string, int]{"key1": 1, "key2": 2}
isPopulated := myMap.IsPopulated()
fmt.Println(isPopulated) // true

Keys

Returns a slice containing all keys in the hash table.

myMap := &gomap.Map[string, int]{"key1": 1, "key2": 2}
keys := myMap.Keys()
fmt.Println(keys) // &["key1" "key2"]

KeysFunc

Returns a slice containing keys that satisfy the given function.

myMap := &gomap.Map[string, int]{"key1": 1, "key2": 2, "key3": 3}
keys := myMap.KeysFunc(func(key string) bool {
    return key != "key3"
})
fmt.Println(keys) // &["key1" "key2"]

Length

Returns the number of key-value pairs in the hash table.

myMap := &gomap.Map[string, int]{"key1": 1, "key2": 2}
length := myMap.Length()
fmt.Println(length) // 2

Map

Applies the given function to each key-value pair in the hash table and replaces the value with the result of the function.

myMap := &gomap.Map[string, int]{"key1": 1, "key2": 2}
myMap.Map(func(key string, value int) int {
    return value * 2
})
fmt.Println(myMap) // &map[key1:2 key2:4]

MapBreak

Applies the given function to each key-value pair in the hash table and replaces the value with the result of the function. It breaks the iteration if the function returns false.

myMap := &gomap.Map[string, int]{"key1": 1, "key2": 2}
myMap.MapBreak(func(key string, value int) (int, bool) {
    return value * 2, key != "key2"
})
fmt.Println(myMap) // &map[key1:2 key2:2]

Merge

Merges the current hash table with another hash table and returns the updated hash table.

myMap1 := &gomap.Map[string, int]{"key1": 1, "key2": 2}
myMap2 := &gomap.Map[string, int]{"key2": 3, "key3": 4}
mergedHashtable := myMap1.Merge(myMap2)
fmt.Println(mergedHashtable) // &map[key1:1 key2:3 key3:4]

MergeFunc

Merges the current hash table with another hash table using a custom function and returns the updated hash table.

myMap1 := &gomap.Map[string, int]{"key1": 1, "key2": 2}
myMap2 := &gomap.Map[string, int]{"key2": 3, "key3": 4}
mergedHashtable := myMap1.MergeFunc(myMap2, func(key string, value1 int, value2 int) bool {
    return value1 > value2
})
fmt.Println(mergedHashtable) // &map[key1:1 key2:2 key3:4]

MergeMany

Merges the current hash table with multiple other hash tables and returns the updated hash table.

myMap1 := &gomap.Map[string, int]{"key1": 1, "key2": 2}
myMap2 := &gomap.Map[string, int]{"key2": 3, "key3": 4}
mergedHashtable := myMap1.MergeMany(myMap2, &gomap.Map[string, int]{"key4": 5})
fmt.Println(mergedHashtable) // &map[key1:1 key2:3 key3:4 key4:5]

MergeManyFunc

Merges the current hash table with multiple other hash tables using a custom function and returns the updated hash table.

myMap1 := &gomap.Map[string, int]{"key1": 1, "key2": 2}
myMap2 := &gomap.Map[string, int]{"key2": 3, "key3": 4}
mergedHashtable := myMap1.MergeManyFunc([]*gomap.Map[string, int]{myMap2}, func(i int, key string, value int) bool {
    return key != "key3"
})
fmt.Println(mergedHashtable) // &map[key1:1 key2:3]

Not

Checks if the given key is not present in the hash table.

myMap := &gomap.Map[string, int]{"key1": 1, "key2": 2}
notPresent := myMap.Not("key3")
fmt.Println(notPresent) // true

NotMany

Checks if multiple keys are not present in the hash table and returns a slice indicating their absence.

myMap := &gomap.Map[string, int]{"key1": 1, "key2": 2}
absentKeys := myMap.NotMany("key3", "key4")
fmt.Println(absentKeys) // &[true true]

Pop

Removes the specified key and its associated value from the hash table and returns the value.

myMap := &gomap.Map[string, int]{"key1": 1, "key2": 2}
value := myMap.Pop("key1")
fmt.Println(value) // 1
fmt.Println(myMap) // &map[key2:2]

PopMany

Removes multiple keys and their associated values from the hash table and returns the values in a slice.

myMap := &gomap.Map[string, int]{"key1": 1, "key2": 2, "key3": 3}
values := myMap.PopMany("key1", "key3")
fmt.Println(values) // &[1 3]
fmt.Println(myMap) // &map[key2:2]

PopManyFunc

Removes key-value pairs from the hash table using a custom function and returns the values in a slice.

myMap := &gomap.Map[string, int]{"key1": 1, "key2": 2, "key3": 3}
values := myMap.PopManyFunc(func(key string, value int) bool {
    return key != "key2"
})
fmt.Println(values) // &[1 3]
fmt.Println(myMap) // &map[key2:2]

PopOK

Removes the specified key and its associated value from the hash table and returns the value along with a boolean indicating existence.

myMap := &gomap.Map[string, int]{"key1": 1, "key2": 2}
value, exists := myMap.PopOK("key1")
fmt.Println(value, exists) // 1 true
fmt.Println(myMap)  // &map[key2:2]

ReplaceMany

Applies the given function to each key-value pair in the hash table and replaces the value if the function returns true. It returns the updated hash table.

myMap := &gomap.Map[string, int]{"key1": 1, "key2": 2, "key3": 3}
myMap.ReplaceMany(func(key string, value int) (int, bool) {
    if key == "key2" {
        return value * 2, true
    }
    return value, false
})
fmt.Println(myMap) // &map[key1:1 key2:4 key3:3]

TakeFrom

Empties the current hash table and inserts its content into another hash table. It returns the updated destination hash table.

source := &gomap.Map[string, int]{"key1": 1, "key2": 2}
destination := &gomap.Map[string, int]{"key3": 3}
destination = source.TakeFrom(destination)
fmt.Println(destination) // &map[key1:1 key2:2]

Values

Returns a slice containing all values in the hash table.

myMap := &gomap.Map[string, int]{"key1": 1, "key2": 2}
values := myMap.Values()
fmt.Println(values) // &[1 2]

ValuesFunc

Returns a slice containing values that satisfy the given function.

myMap := &gomap.Map[string, int]{"key1": 1, "key2": 2, "key3": 3}
values := myMap.ValuesFunc(func(key string, value int) bool {
    return value%2 == 0
})
fmt.Println(values) // &[2]

Examples

Struct

Using a custom struct.

package main

import (
	"fmt"
	"github.com/lindsaygelle/gomap" // Import the gomap package
)

type Animal struct {
	Age     int
	Name    string
	Species string
}

func main() {
	// Create a new Animal
	fluffy := Animal{Age: 1, Name: "Fluffy", Species: "Cat"}

	// Create a new Map of Animals
	animals := &gomap.Map[string, Animal]{}

	// Add an Animal to the Map using Add function
	animals.Add(fluffy.Name, fluffy)

	// Check if the Map contains a specific key
	if animals.Has("Fluffy") {
		fmt.Println("Fluffy is in the Map!")
	}

	// Get the value associated with a specific key
	if animal, exists := animals.Get("Fluffy"); exists {
		fmt.Println("Found Fluffy in the Map:", animal)
	}

	// Update the age of Fluffy
	updatedFluffy := Animal{Age: 2, Name: "Fluffy", Species: "Cat"}
	animals.Add("Fluffy", updatedFluffy)

	// Delete an entry from the Map
	animals.Delete("Fluffy")

	// Add more animals after deleting Fluffy
	animals.Add("Buddy", Animal{Age: 3, Name: "Buddy", Species: "Dog"})
	animals.Add("Whiskers", Animal{Age: 2, Name: "Whiskers", Species: "Rabbit"})

	// Iterate over the Map and print each key-value pair
	animals.Each(func(key string, value Animal) {
		fmt.Println("Key:", key, "Value:", value)
	})

	// Check if the Map is empty
	if animals.IsEmpty() {
		fmt.Println("Map is empty.")
	} else {
		fmt.Println("Map is not empty.")
	}

	// Get all keys from the Map
	keys := animals.Keys().Slice()
	fmt.Println("Keys in Map:", keys)

	// Get all values from the Map
	values := animals.Values().Slice()
	fmt.Println("Values in Map:", values)
}

Chaining

Chaining methods together.

package main

import (
	"fmt"
	"github.com/lindsaygelle/gomap" // Import the gomap package
)

type Animal struct {
	Age     int
	Name    string
	Species string
}

func main() {
	// Create a new Map of Animals and add animals using method chaining
	animals := &gomap.Map[string, Animal]{}.
		Add("Fluffy", Animal{Age: 1, Name: "Fluffy", Species: "Cat"}).
		Add("Buddy", Animal{Age: 3, Name: "Buddy", Species: "Dog"}).
		Add("Whiskers", Animal{Age: 2, Name: "Whiskers", Species: "Rabbit"})

	// Print the number of animals in the Map using the Length() method
	fmt.Println("Number of animals in the Map:", animals.Length())

	// Check if a specific animal is in the Map using method chaining
	if exists := animals.Has("Fluffy"); exists {
		fmt.Println("Fluffy is in the Map!")
	}

	// Retrieve and print the age of a specific animal using method chaining
	if age, exists := animals.Get("Buddy"); exists {
		fmt.Println("Buddy's age is:", age.Age)
	}

	// Iterate over the Map and print each key-value pair using method chaining
	animals.Each(func(key string, value Animal) {
		fmt.Println("Key:", key, "Value:", value)
	})

	// Chain filtering and mapping methods to filter out specific animals and update their ages
	animals.
		Filter(func(key string, value Animal) bool {
			return value.Age > 1
		}).
		Map(func(key string, value Animal) Animal {
			value.Age++
			return value
		})

	// Print the updated ages of animals after filtering and mapping using method chaining
	fmt.Println("Ages of animals after filtering and mapping:")
	animals.Each(func(key string, value Animal) {
		fmt.Println("Key:", key, "Value:", value)
	})
}

Docker

A Dockerfile is provided for individuals that prefer containerized development.

Building

Building the Docker container:

docker build . -t gomap

Running

Developing and running Go within the Docker container:

docker run -it --rm --name gomap gomap

Docker Compose

A docker-compose file has also been included for convenience:

Running

Running the compose file.

docker-compose up -d

Contributing

We warmly welcome contributions to Map. Whether you have innovative ideas, bug reports, or enhancements in mind, please share them with us by submitting GitHub issues or creating pull requests. For substantial contributions, it's a good practice to start a discussion by creating an issue to ensure alignment with the project's goals and direction. Refer to the CONTRIBUTING file for comprehensive details.

Branching

For a smooth collaboration experience, we have established branch naming conventions and guidelines. Please consult the BRANCH_NAMING_CONVENTION document for comprehensive information and best practices.

License

Map is released under the MIT License, granting you the freedom to use, modify, and distribute the code within this repository in accordance with the terms of the license. For additional information, please review the LICENSE file.

Security

If you discover a security vulnerability within this project, please consult the SECURITY document for information and next steps.

Code Of Conduct

This project has adopted the Amazon Open Source Code of Conduct. For additional information, please review the CODE_OF_CONDUCT file.

Acknowledgements

Big thanks to egonelbre/gophers for providing the delightful Gopher artwork used in the social preview. Don't hesitate to pay them a visit!

Documentation

Overview

Package gomap provides a generic map implementation that maps keys of type K to values of type V.

Index

• type Map
  • func (gomap *Map[K, V]) Add(key K, value V) *Map[K, V]
  • func (gomap *Map[K, V]) AddLength(key K, value V) int
  • func (gomap *Map[K, V]) AddMany(values ...map[K]V) *Map[K, V]
  • func (gomap *Map[K, V]) AddManyFunc(values []map[K]V, fn func(i int, key K, value V) bool) *Map[K, V]
  • func (gomap *Map[K, V]) AddManyOK(values ...map[K]V) *slice.Slice[bool]
  • func (gomap *Map[K, V]) AddOK(key K, value V) bool
  • func (gomap *Map[K, V]) Contains(value V) (K, bool)
  • func (gomap *Map[K, V]) Delete(key K) *Map[K, V]
  • func (gomap *Map[K, V]) DeleteLength(key K) int
  • func (gomap *Map[K, V]) DeleteMany(keys ...K) *Map[K, V]
  • func (gomap *Map[K, V]) DeleteManyFunc(fn func(key K, value V) bool) *Map[K, V]
  • func (gomap *Map[K, V]) DeleteManyOK(keys ...K) *slice.Slice[bool]
  • func (gomap *Map[K, V]) DeleteManyValues(values ...V) *Map[K, V]
  • func (gomap *Map[K, V]) DeleteOK(key K) bool
  • func (gomap *Map[K, V]) Each(fn func(key K, value V)) *Map[K, V]
  • func (gomap *Map[K, V]) EachBreak(fn func(key K, value V) bool) *Map[K, V]
  • func (gomap *Map[K, V]) EachKey(fn func(key K)) *Map[K, V]
  • func (gomap *Map[K, V]) EachKeyBreak(fn func(key K) bool) *Map[K, V]
  • func (gomap *Map[K, V]) EachValue(fn func(value V)) *Map[K, V]
  • func (gomap *Map[K, V]) EachValueBreak(fn func(value V) bool) *Map[K, V]
  • func (gomap *Map[K, V]) EmptyInto(other *Map[K, V]) *Map[K, V]
  • func (gomap *Map[K, V]) Equal(other *Map[K, V]) bool
  • func (gomap *Map[K, V]) EqualFunc(other *Map[K, V], fn func(a V, b V) bool) bool
  • func (gomap *Map[K, V]) EqualLength(other *Map[K, V]) bool
  • func (gomap *Map[K, V]) Fetch(key K) V
  • func (gomap *Map[K, V]) Filter(fn func(key K, value V) bool) *Map[K, V]
  • func (gomap *Map[K, V]) Get(key K) (V, bool)
  • func (gomap *Map[K, V]) GetMany(keys ...K) *slice.Slice[V]
  • func (gomap *Map[K, V]) Has(key K) bool
  • func (gomap *Map[K, V]) HasMany(keys ...K) *slice.Slice[bool]
  • func (gomap *Map[K, V]) Intersection(other *Map[K, V]) *Map[K, V]
  • func (gomap *Map[K, V]) IntersectionFunc(other *Map[K, V], fn func(key K, a V, b V) bool) *Map[K, V]
  • func (gomap *Map[K, V]) IsEmpty() bool
  • func (gomap *Map[K, V]) IsPopulated() bool
  • func (gomap *Map[K, V]) Keys() *slice.Slice[K]
  • func (gomap *Map[K, V]) KeysFunc(fn func(key K) bool) *slice.Slice[K]
  • func (gomap *Map[K, V]) Length() int
  • func (gomap *Map[K, V]) Map(fn func(key K, value V) V) *Map[K, V]
  • func (gomap *Map[K, V]) MapBreak(fn func(key K, value V) (V, bool)) *Map[K, V]
  • func (gomap *Map[K, V]) Merge(other *Map[K, V]) *Map[K, V]
  • func (gomap *Map[K, V]) MergeFunc(other *Map[K, V], fn func(key K, value V) bool) *Map[K, V]
  • func (gomap *Map[K, V]) MergeMany(others ...*Map[K, V]) *Map[K, V]
  • func (gomap *Map[K, V]) MergeManyFunc(others []*Map[K, V], fn func(i int, key K, value V) bool) *Map[K, V]
  • func (gomap *Map[K, V]) Not(key K) bool
  • func (gomap *Map[K, V]) NotMany(keys ...K) *slice.Slice[bool]
  • func (gomap *Map[K, V]) Pop(key K) V
  • func (gomap *Map[K, V]) PopMany(keys ...K) *slice.Slice[V]
  • func (gomap *Map[K, V]) PopManyFunc(fn func(key K, value V) bool) *slice.Slice[V]
  • func (gomap *Map[K, V]) PopOK(key K) (V, bool)
  • func (gomap *Map[K, V]) ReplaceMany(fn func(key K, value V) (V, bool)) *Map[K, V]
  • func (gomap *Map[K, V]) TakeFrom(other *Map[K, V]) *Map[K, V]
  • func (gomap *Map[K, V]) Values() *slice.Slice[V]
  • func (gomap *Map[K, V]) ValuesFunc(fn func(key K, value V) bool) *slice.Slice[V]

Types

type Map

type Map[K comparable, V any] map[K]V

Map represents a generic map that maps keys of type K to values of type V.

func (*Map[K, V]) Add

func (gomap *Map[K, V]) Add(key K, value V) *Map[K, V]

Add inserts a new key-value pair into the map or updates the existing value associated with the provided key. If the key already exists, the corresponding value is updated. If the key is new, a new key-value pair is added to the map.

// Create a new Map instance.
newMap := make(gomap.Map[string, int])
newMap.Add("apple", 5)
newMap.Add("banana", 3)
newMap.Add("cherry", 8)
newMap.Add("banana", 10) // Updates the value for the key "banana" to 10
fmt.Println(newMap) // &map[apple:5 banana:10 cherry:8]

func (*Map[K, V]) AddLength

func (gomap *Map[K, V]) AddLength(key K, value V) int

AddLength inserts a new key-value pair into the map or updates the existing value associated with the provided key. If the key already exists, the corresponding value is updated. If the key is new, a new key-value pair is added to the map. It then returns the current length of the map after the addition or update operation.

// Create a new Map instance.
newMap := make(gomap.Map[string, int])
length := newMap.AddLength("apple", 5)  // Adds "apple" with value 5, returns the length of the map (1 in this case)
length = newMap.AddLength("apple", 10)  // Updates the value for "apple" to 10, returns the length of the map (1)
length = newMap.AddLength("banana", 3)  // Adds "banana" with value 3, returns the length of the map (2)

func (*Map[K, V]) AddMany

func (gomap *Map[K, V]) AddMany(values ...map[K]V) *Map[K, V]

AddMany inserts multiple key-value pairs into the map. It accepts a variadic number of maps, where each map contains key-value pairs to be added to the map. If a key already exists in the gomap, the corresponding value is updated with the new value from the input maps.

// Create a new Map instance.
newMap := make(gomap.Map[string, int])
newMap.AddMany(map[string]int{"orange": 7, "grape": 4}, map[string]int{"kiwi": 6, "pear": 9})
fmt.Println(newMap) // &map[orange:7 grape:4 kiwi:6 pear:9]

func (*Map[K, V]) AddManyFunc

func (gomap *Map[K, V]) AddManyFunc(values []map[K]V, fn func(i int, key K, value V) bool) *Map[K, V]

AddManyFunc inserts key-value pairs into the map based on a provided condition function. It accepts a slice of maps, where each map contains key-value pairs. For each key-value pair, the specified function is called. If the function returns true, the pair is added to the map.

// Create a new Map instance.
newMap := make(gomap.Map[string, int])
newMap.AddManyFunc([]map[K]V{{"apple": 5, "orange": -3, "banana": 10}}, func(i int, key string, value int) bool {
	return value > 0 // Add key-value pairs with values greater than 0
})
fmt.Println(newMap) // &map[apple:5 banana:10]

func (*Map[K, V]) AddManyOK

func (gomap *Map[K, V]) AddManyOK(values ...map[K]V) *slice.Slice[bool]

AddManyOK inserts multiple key-value pairs into the map and returns a slice of booleans indicating whether each insertion was successful. It accepts a variadic number of maps, where each map contains key-value pairs to be added to the map. For each key-value pair, it checks if the key already exists in the map. If the key is not present, the pair is added, and the corresponding boolean in the returned slice is true. If the key already exists, the pair is not added, and the boolean is false.

// Create a new Map instance.
newMap := make(gomap.Map[string, int])
results := newMap.AddManyOK(map[string]int{"apple": 5, "orange": 3}, map[string]int{"orange": 10, "banana": 7})
// Returns a slice containing [true, false, true] indicating successful insertions for "apple" and "banana"

func (*Map[K, V]) AddOK

func (gomap *Map[K, V]) AddOK(key K, value V) bool

AddOK inserts a new key-value pair into the map only if the key does not already exist in the map. If the key already exists, the insertion fails, and false is returned. If the key is new, a new key-value pair is added to the gomap, and true is returned to indicate a successful insertion.

// Create a new Map instance.
newMap := make(gomap.Map[string, int])

// Attempt to add key-value pairs.
added := newMap.AddOK("apple", 5)    // added is true, "apple" is added with value 5.
reAdded := newMap.AddOK("apple", 10)  // reAdded is false, "apple" already exists with value 5, no change is made.
addedNew := newMap.AddOK("banana", 3) // addedNew is true, "banana" is added with value 3.

func (*Map[K, V]) Contains

func (gomap *Map[K, V]) Contains(value V) (K, bool)

Contains checks if the given value is present in the map and returns the first key-value pair that matches the value. It takes a value as input and returns the key and a boolean indicating whether the value is found in the map. If the value is found, it returns the corresponding key and true. If the value is not found, it returns the zero value for the key type and false.

// Create a new Map instance.
newMap := make(gomap.Map[string, int])
key, found := newMap.Contains(5)  // Checks if value 5 is in the gomap, returns the key ("apple" for example) and true if found, or ("", false) if not found

func (*Map[K, V]) Delete

func (gomap *Map[K, V]) Delete(key K) *Map[K, V]

Delete removes a key-value pair from the map based on the provided key. If the key exists in the gomap, it is deleted, and the modified map is returned. If the key is not found, the map remains unchanged.

// Create a new Map instance.
newMap := make(gomap.Map[string, int])
newMap.Add("apple", 5)
newMap.Add("banana", 3)

// Delete the key-value pair with the key "apple".
newMap.Delete("apple")
fmt.Println(newMap) // &map[banana:3]

func (*Map[K, V]) DeleteLength

func (gomap *Map[K, V]) DeleteLength(key K) int

DeleteLength removes a key-value pair from the map based on the provided key. If the key exists in the gomap, it is deleted, and the current length of the map after the deletion is returned. If the key is not found, the map remains unchanged, and the current length is returned.

// Create a new Map instance.
newMap := make(gomap.Map[string, int])
newMap.Add("apple", 5)
newMap.Add("banana", 3)

// Delete the key-value pair with the key "apple" and get the updated length of the map.
length := newMap.DeleteLength("apple")
// After deletion, the length of the map is 1.
// The current length returned: 1

func (*Map[K, V]) DeleteMany

func (gomap *Map[K, V]) DeleteMany(keys ...K) *Map[K, V]

DeleteMany removes multiple key-value pairs from the map based on the provided keys. If a key exists in the gomap, it is deleted.

// Create a new Map instance.
newMap := make(gomap.Map[string, int])
newMap.Add("apple", 5)
newMap.Add("banana", 3)

// Delete key-value pairs with the keys "apple" and "banana".
newMap.DeleteMany("apple", "banana")
fmt.Println(newMap) // &map[]

func (*Map[K, V]) DeleteManyFunc

func (gomap *Map[K, V]) DeleteManyFunc(fn func(key K, value V) bool) *Map[K, V]

DeleteFunc removes key-value pairs from the map based on the provided function. The function is applied to each key-value pair, and if it returns true, the corresponding key-value pair is deleted from the map.

// Create a new Map instance.
newMap := make(gomap.Map[string, int])
newMap.Add("apple", 5)
newMap.Add("banana", 3)

// Delete key-value pairs where the value is less than 4.
newMap.DeleteFunc(func(key string, value int) bool {
	return value < 4
})
fmt.Println(newMap) // &map[apple:5]

func (*Map[K, V]) DeleteManyOK

func (gomap *Map[K, V]) DeleteManyOK(keys ...K) *slice.Slice[bool]

DeleteManyOK removes multiple key-value pairs from the map based on the provided keys. If a key exists in the gomap, it is deleted, and true is appended to the result slice to indicate a successful deletion. If the key is not found, false is appended.

// Create a new Map instance.
newMap := make(gomap.Map[string, int])
newMap.Add("apple", 5)
newMap.Add("banana", 3)

// Attempt to delete key-value pairs with the keys "apple" and "orange".
results := newMap.DeleteManyOK("apple", "orange")
// Results after deletion: []bool{true, false}
// The first deletion succeeded ("apple": 5 was deleted), and the second deletion failed as "orange" was not found.

func (*Map[K, V]) DeleteManyValues

func (gomap *Map[K, V]) DeleteManyValues(values ...V) *Map[K, V]

DeleteManyValues removes key-value pairs from the map based on the provided values. If a value exists in the gomap, the corresponding key-value pair is deleted.

// Create a new Map instance.
newMap := make(gomap.Map[string, int])
newMap.Add("apple", 5)
newMap.Add("banana", 3)

// Delete key-value pairs with the values 5 and 10.
newMap.DeleteManyValues(5, 10)
// Map after deletion: {"banana": 3}

func (*Map[K, V]) DeleteOK

func (gomap *Map[K, V]) DeleteOK(key K) bool

DeleteOK removes a key-value pair from the map based on the provided key. If the key exists in the gomap, it is deleted, and true is returned to indicate a successful deletion. If the key is not found, the map remains unchanged, and false is returned to indicate that the deletion failed.

// Create a new Map instance.
newMap := make(gomap.Map[string, int])
newMap.Add("apple", 5)
newMap.Add("banana", 3)

// Attempt to delete the key-value pair with the key "apple".
success := newMap.DeleteOK("apple")
// After deletion, the key "apple" is not found in the map.
// Deletion success: true

// Attempt to delete a non-existing key.
success = newMap.DeleteOK("orange")
// The key "orange" does not exist in the map.
// Deletion failed: false

func (*Map[K, V]) Each

func (gomap *Map[K, V]) Each(fn func(key K, value V)) *Map[K, V]

Each iterates over the key-value pairs in the map and applies a function to each pair.

// Create a new Map instance.
newMap := make(gomap.Map[string, int])
newMap.Add("apple", 5)
newMap.Add("banana", 3)
newMap.Add("cherry", 8)

// Iterate over the map and print all key-value pairs.
newMap.Each(func(key string, value int) {
    fmt.Println(key, value)
})
// Output: "apple 5", "banana 3", "cherry 8"

func (*Map[K, V]) EachBreak

func (gomap *Map[K, V]) EachBreak(fn func(key K, value V) bool) *Map[K, V]

EachBreak applies the provided function to each key-value pair in the map. The function is applied to key-value pairs in the map until the provided function returns false. If the function returns false for any key-value pair, the iteration breaks early.

// Create a new Map instance.
newMap := make(gomap.Map[string, int])
newMap.Add("apple", 5)
newMap.Add("banana", 3)
newMap.Add("cherry", 8)

// Function to print key-value pairs until finding "banana".
stopPrinting := newMap.EachBreak(func(key string, value int) bool {
    fmt.Println(key, value)
    return key != "banana" // Continue printing until "banana" is encountered.
})
// Output: "apple 5", "banana 3"

func (*Map[K, V]) EachKey

func (gomap *Map[K, V]) EachKey(fn func(key K)) *Map[K, V]

EachKey iterates over the keys in the map and applies a function to each key.

// Create a new Map instance.
newMap := make(gomap.Map[string, int])
newMap.Add("apple", 5)
newMap.Add("banana", 3)
newMap.Add("cherry", 8)

// Iterate over the map and print each key.
newMap.EachKey(func(key string) {
    fmt.Println(key)
})
// Output: "apple", "banana", "cherry"

func (*Map[K, V]) EachKeyBreak

func (gomap *Map[K, V]) EachKeyBreak(fn func(key K) bool) *Map[K, V]

EachKeyBreak iterates over the keys in the map and applies a function to each key. It allows breaking the iteration early if the provided function returns false.

// Create a new Map instance.
newMap := make(gomap.Map[string, int])
newMap.Add("apple", 5)
newMap.Add("banana", 3)
newMap.Add("cherry", 8)

// Iterate over the map keys, print them, and break when "banana" is encountered.
newMap.EachKeyBreak(func(key string) bool {
    fmt.Println(key)
    return key != "banana"
})
// Output: "apple", "banana"

func (*Map[K, V]) EachValue

func (gomap *Map[K, V]) EachValue(fn func(value V)) *Map[K, V]

EachValue iterates over the values in the map and applies a function to each value.

// Create a new Map instance.
newMap := make(gomap.Map[string, int])
newMap.Add("apple", 5)
newMap.Add("banana", 3)
newMap.Add("cherry", 8)

// Iterate over the map values and print them.
newMap.EachValue(func(value int) {
    fmt.Println(value)
})
// Output: 5, 3, 8

func (*Map[K, V]) EachValueBreak

func (gomap *Map[K, V]) EachValueBreak(fn func(value V) bool) *Map[K, V]

EachValueBreak iterates over the values in the map and applies a function to each value until the function returns false. If the provided function returns false, the iteration breaks early.

// Create a new Map instance.
newMap := make(gomap.Map[string, int])
newMap.Add("apple", 5)
newMap.Add("banana", 3)
newMap.Add("cherry", 8)

// Iterate over the map values and process them until the value is 3.
newMap.EachValueBreak(func(value int) bool {
    fmt.Println(value)
    return value != 3
})
// Output: 5, 3

func (*Map[K, V]) EmptyInto

func (gomap *Map[K, V]) EmptyInto(other *Map[K, V]) *Map[K, V]

EmptyInto transfers all key-value pairs from the current map into another gomap, emptying the current map. It takes another map as input and adds all key-value pairs from the current map to the other map.

// Create a new Map instance.
newMap1 := make(gomap.Map[string, int])
newMap1.Add("apple", 5)
// Create a new Map instance.
newMap2 := make(gomap.Map[string, int])

newMap1.EmptyInto(newMap2)  // Transfers "apple": 5 from newMap1 to newMap2, leaving newMap1 empty

func (*Map[K, V]) Equal

func (gomap *Map[K, V]) Equal(other *Map[K, V]) bool

Equal checks if the current map is equal to another map by comparing the key-value pairs directly using reflect.DeepEqual. It takes another map as input and returns true if the two hashtables are equal, false otherwise.

// Create a new Map instance.
newMap1 := make(gomap.Map[string, int])
newMap1.Add("apple", 5)
newMap1.Add("orange", 10)

// Create a new Map instance.
newMap2 := make(gomap.Map[string, int])
newMap2.Add("apple", 5)
newMap2.Add("orange", 10)

equal := newMap1.Equal(newMap2)  // Returns true because newMap1 and newMap2 have the same key-value pairs

func (*Map[K, V]) EqualFunc

func (gomap *Map[K, V]) EqualFunc(other *Map[K, V], fn func(a V, b V) bool) bool

EqualFunc checks if the current map is equal to another map based on a provided comparison function. It takes another map and a comparison function as input and returns true if the two hashtables are equal according to the function. The comparison function takes two values as input and returns true if they are considered equal, false otherwise.

// Create a new Map instance.
newMap1 := make(gomap.Map[string, int])
newMap1.Add("apple", 5)
newMap1.Add("orange", 10)

// Create a new Map instance.
newMap2 := make(gomap.Map[string, int])
newMap2.Add("apple", 5)
newMap2.Add("orange", 11)

equal := newMap1.EqualFunc(newMap2, func(a, b int) bool {
	return math.Abs(float64(a - b)) <= 1
})  // Returns true because the values for "orange" (10 and 11) have a difference of 1, within the allowed range

func (*Map[K, V]) EqualLength

func (gomap *Map[K, V]) EqualLength(other *Map[K, V]) bool

EqualLength checks if the current map has the same length as another map. It takes another map as input and returns true if the two hashtables have the same length, false otherwise.

// Create a new Map instance.
newMap1 := make(gomap.Map[string, int])
newMap1.Add("apple", 5)
newMap1.Add("orange", 10)

// Create a new Map instance.
newMap2 := make(gomap.Map[string, int])
newMap2.Add("apple", 5)

equalLength := newMap1.EqualLength(newMap2)  // Returns false because newMap1 has a length of 2, while newMap2 has a length of 1

func (*Map[K, V]) Fetch

func (gomap *Map[K, V]) Fetch(key K) V

Fetch retrieves the value associated with the given key from the map. It returns the value if the key is found in the gomap, and the zero value for the value type if the key is not present.

// Create a new Map instance.
newMap := make(gomap.Map[string, int])
newMap.Add("apple", 5)
value := newMap.Fetch("apple")  // Returns 5, the value associated with the key "apple"
value = newMap.Fetch("orange")  // Returns 0 because "orange" is not in the gomap

func (*Map[K, V]) Filter

func (gomap *Map[K, V]) Filter(fn func(key K, value V) bool) *Map[K, V]

Filter applies the given function to each key-value pair in the map and returns a new gomap containing only the key-value pairs for which the function returns true. The original map is not modified.

// Create a new Map instance.
newMap := make(gomap.Map[string, int])
newMap.Add("apple", 5)
newMap.Add("banana", 3)
newMap.Add("cherry", 8)

// Create a new map containing key-value pairs where the value is greater than 4.
filteredMap := newMap.Filter(func(key string, value int) bool {
	return value > 4
})

func (*Map[K, V]) Get

func (gomap *Map[K, V]) Get(key K) (V, bool)

Get retrieves the value associated with the provided key from the map. If the key exists, it returns the associated value and true. Otherwise, it returns the zero value for the value type and false.

// Create a new Map instance.
newMap := make(gomap.Map[string, int])
newMap.Add("apple", 5)
value, exists := newMap.Get("apple") // 5, true
value, exists = newMap.Get("orange")  // 0, false

func (*Map[K, V]) GetMany

func (gomap *Map[K, V]) GetMany(keys ...K) *slice.Slice[V]

GetMany retrieves the values associated with the provided keys from the map. It accepts a variadic number of keys, and returns a slice containing the values corresponding to the keys found in the map. If a key is not found in the gomap, the corresponding position in the returned slice will be the zero value for the value type.

// Create a new Map instance.
newMap := make(gomap.Map[string, int])
newMap.Add("apple", 5)
newMap.Add("banana", 3)
newMap.Add("cherry", 8)

// Get values for specific keys.
values := newMap.GetMany("apple", "banana", "orange") // The resulting values slice: {5, 3}

func (*Map[K, V]) Has

func (gomap *Map[K, V]) Has(key K) bool

Has checks if the provided key exists in the map. It returns true if the key exists, and false otherwise.

// Create a new Map instance.
newMap := make(gomap.Map[string, int])
newMap.Add("apple", 5)
exists := newMap.Has("apple") // true
exists = newMap.Has("orange")  // false

func (*Map[K, V]) HasMany

func (gomap *Map[K, V]) HasMany(keys ...K) *slice.Slice[bool]

HasMany checks the existence of multiple keys in the map and returns a slice of boolean values indicating whether each corresponding key exists in the map.

// Create a new Map instance.
newMap := make(gomap.Map[string, int])
newMap.Add("apple", 5)
newMap.Add("banana", 3)
newMap.Add("cherry", 8)

// Check the existence of multiple keys.
keysToCheck := []string{"apple", "orange", "banana"}
results := newMap.HasMany(keysToCheck...)

// The resulting boolean slice: {true, false, true}

func (*Map[K, V]) Intersection

func (gomap *Map[K, V]) Intersection(other *Map[K, V]) *Map[K, V]

Intersection creates a new map containing key-value pairs that exist in both the current map and another map. It compares values using reflect.DeepEqual to determine equality between the pairs. It takes another map as input and returns a new map containing the intersecting key-value pairs.

// Create a new Map instance.
newMap1 := make(gomap.Map[string, int])
newMap1.Add("apple", 5)

// Create a new Map instance.
newMap2 := make(gomap.Map[string, int])
newMap2.Add("apple", 5)
newMap2.Add("orange", 10)

newMap := newMap1.Intersection(newMap2)  // Creates a new map with the pair "apple": 5

func (*Map[K, V]) IntersectionFunc

func (gomap *Map[K, V]) IntersectionFunc(other *Map[K, V], fn func(key K, a V, b V) bool) *Map[K, V]

IntersectionFunc creates a new map containing key-value pairs that exist in both the current map and another map. It takes another map and a condition function as input and adds key-value pairs from the current map to the new gomap if the condition function evaluates to true for the corresponding key-value pair in the other map.

// Create a new Map instance.
newMap1 := make(gomap.Map[string, int])
newMap1.Add("apple", 5)
newMap1.Add("orange", 8)

// Create a new Map instance.
newMap2 := make(gomap.Map[string, int])
newMap2.Add("orange", 8)
newMap2.Add("banana", 6)

newMap := newMap1.IntersectionFunc(newMap2, func(key string, a, b int) bool {
	return a == b
})  // Creates a new map with the pair "orange": 8

func (*Map[K, V]) IsEmpty

func (gomap *Map[K, V]) IsEmpty() bool

IsEmpty checks if the map is empty, i.e., it contains no key-value pairs. It returns true if the map is empty and false otherwise.

// Create a new Map instance.
newMap := make(Map[string, int])
empty := newMap.IsEmpty()  // Returns true since the map is empty

func (*Map[K, V]) IsPopulated

func (gomap *Map[K, V]) IsPopulated() bool

func (*Map[K, V]) Keys

func (gomap *Map[K, V]) Keys() *slice.Slice[K]

Keys returns a slice containing all the keys present in the map.

// Create a new Map instance.
newMap := make(gomap.Map[string, int])
newMap.Add("apple", 5)
newMap.Add("banana", 3)
newMap.Add("cherry", 8)

// Get all keys from the map.
keys := newMap.Keys() // Result: {"apple", "banana", "cherry"}

func (*Map[K, V]) KeysFunc

func (gomap *Map[K, V]) KeysFunc(fn func(key K) bool) *slice.Slice[K]

KeysFunc applies the provided function to each key in the map and returns a slice containing the keys for which the function returns true.

// Create a new Map instance.
newMap := make(gomap.Map[string, int])
newMap.Add("apple", 5)
newMap.Add("banana", 3)
newMap.Add("cherry", 8)

// Get keys from the map where the key length is greater than 5.
keys := newMap.KeysFunc(func(key string) bool {
    return len(key) > 5
})
// Result: {"banana"}

func (*Map[K, V]) Length

func (gomap *Map[K, V]) Length() int

Length returns the number of key-value pairs in the map.

// Create a new Map instance.
newMap := make(gomap.Map[string, int])
newMap.Add("apple", 5)
newMap.Add("banana", 3)
newMap.Add("cherry", 8)

length := newMap.Length() // Result: 3

func (*Map[K, V]) Map

func (gomap *Map[K, V]) Map(fn func(key K, value V) V) *Map[K, V]

Map applies the provided function to each key-value pair in the map and returns a new map containing the mapped key-value pairs. The original map remains unchanged.

// Create a new Map instance.
newMap := make(gomap.Map[string, int])
newMap.Add("apple", 5)
newMap.Add("banana", 3)

// Create a new map with doubled values.
newMap := newMap.Map(func(key string, value int) int {
	return value * 2
})
// New gomap: {"apple": 10, "banana": 6}

func (*Map[K, V]) MapBreak

func (gomap *Map[K, V]) MapBreak(fn func(key K, value V) (V, bool)) *Map[K, V]

MapBreak applies the provided function to each key-value pair in the map. It creates a new map containing the mapped key-value pairs until the function returns false for any pair, at which point the mapping breaks early. The original map remains unchanged.

// Create a new Map instance.
newMap := make(gomap.Map[string, int])
newMap.Add("apple", 5)
newMap.Add("banana", 3)
newMap.Add("cherry", 8)

// Create a new map with doubled values until a value is greater than or equal to 10.
newMap := newMap.MapBreak(func(key string, value int) (int, bool) {
	newValue := value * 2
	return newValue, newValue < 10
})
// New gomap: {"apple": 10, "banana": 6}

func (*Map[K, V]) Merge

func (gomap *Map[K, V]) Merge(other *Map[K, V]) *Map[K, V]

Merge merges all key-value pairs from another map into the current map. It takes another map as input and adds all its key-value pairs to the current map.

// Create a new Map instance.
newMap1 := make(gomap.Map[string, int])
newMap1.Add("apple", 5)

// Create a new Map instance.
newMap2 := make(gomap.Map[string, int])
newMap2.Add("orange", 10)

newMap1.Merge(newMap2)  // Adds "orange": 10 to newMap1

func (*Map[K, V]) MergeFunc

func (gomap *Map[K, V]) MergeFunc(other *Map[K, V], fn func(key K, value V) bool) *Map[K, V]

MergeFunc merges the key-value pairs from another map into the current map based on a provided condition function. It takes another map and a condition function as input and adds key-value pairs from the other map to the current gomap if the condition function evaluates to true for the given key-value pair from the other map.

// Create a new Map instance.
newMap1 := make(gomap.Map[string, int])
newMap1.Add("apple", 5)
newMap1.Add("orange", 10)

// Create a new Map instance.
newMap2 := make(gomap.Map[string, int])
newMap2.Add("orange", 8)
newMap2.Add("banana", 6)

// Condition function to merge pairs where the value in newMap2 is greater than 7
newMap1.MergeFunc(newMap2, func(key string, value int) bool {
	return value > 7
})  // Adds "orange": 8 to newMap1, "banana": 6 does not meet the condition and is not added

func (*Map[K, V]) MergeMany

func (gomap *Map[K, V]) MergeMany(others ...*Map[K, V]) *Map[K, V]

MergeMany merges key-value pairs from multiple hashtables into the current map. It takes a variadic number of hashtables as input and adds all their key-value pairs to the current map.

// Create a new Map instance.
newMap1 := make(gomap.Map[string, int])
newMap1.Add("apple", 5)
// Create a new Map instance.
newMap2 := make(gomap.Map[string, int])
newMap2.Add("orange", 10)
// Create a new Map instance.
newMap3 := make(gomap.Map[string, int])
newMap3.Add("banana", 7)

newMap1.MergeMany(newMap2, newMap3)  // Merges key-value pairs from newMap2 and newMap3 into newMap1

func (*Map[K, V]) MergeManyFunc

func (gomap *Map[K, V]) MergeManyFunc(others []*Map[K, V], fn func(i int, key K, value V) bool) *Map[K, V]

MergeManyFunc merges key-value pairs from multiple hashtables into the current map based on a provided condition function. It takes a slice of hashtables and a condition function as input. For each key-value pair in the other hashtables, the function is applied, and if it evaluates to true, the pair is added to the current map.

// Create a new Map instance.
newMap1 := make(gomap.Map[string, int])
newMap1.Add("apple", 5)
// Create a new Map instance.
newMap2 := make(gomap.Map[string, int])
newMap2.Add("orange", 10)
// Create a new Map instance.
newMap3 := make(gomap.Map[string, int])
newMap3.Add("banana", 7)

// Condition function to include pairs from the second map only if the value is greater than 7
newMap1.MergeManyFunc([]*Map[string, int]{newMap2, newMap3}, func(i int, key string, value int) bool {
	return value > 7
})

func (*Map[K, V]) Not

func (gomap *Map[K, V]) Not(key K) bool

Not checks if the given key is not present in the map. It returns true if the key is not found, and false if the key exists in the map.

// Create a new Map instance.
newMap := make(gomap.Map[string, int])
result := newMap.Not("apple")  // Returns true if "apple" is not in the gomap, false otherwise

func (*Map[K, V]) NotMany

func (gomap *Map[K, V]) NotMany(keys ...K) *slice.Slice[bool]

NotMany checks if multiple keys are not present in the map. It takes a variadic number of keys as input and returns a slice of booleans indicating whether each key is not found in the map. For each key, if it is not present in the gomap, the corresponding boolean in the returned slice is true. Otherwise, it is false.

// Create a new Map instance.
newMap := make(gomap.Map[string, int])
results := newMap.NotMany("apple", "orange", "banana")
// Returns a slice containing [true, true, false] indicating "apple" and "orange" are not in the gomap, but "banana" is present

func (*Map[K, V]) Pop

func (gomap *Map[K, V]) Pop(key K) V

Pop removes a key-value pair from the map based on the provided key and returns the removed value. If the key is found in the gomap, the corresponding value is returned. If the key is not present, the zero value for the value type is returned.

// Create a new Map instance.
newMap := make(gomap.Map[string, int])
newMap.Add("apple", 5)
removedValue := newMap.Pop("apple")  // Removes the key "apple" and returns its associated value 5, or 0 if "apple" is not found

func (*Map[K, V]) PopMany

func (gomap *Map[K, V]) PopMany(keys ...K) *slice.Slice[V]

PopMany removes multiple key-value pairs from the map based on the provided keys. It takes a variadic number of keys as input and removes the corresponding key-value pairs from the map. It returns a slice containing the removed values and does not guarantee any specific order of values in the result. If a key is not found in the gomap, the corresponding value in the result slice will be the zero value for the value type.

// Create a new Map instance.
newMap := make(gomap.Map[string, int])
newMap.Add("apple", 5)
newMap.Add("banana", 3)
removedValues := newMap.PopMany("apple", "orange")  // Removes "apple", returns a slice containing [5, 0]

func (*Map[K, V]) PopManyFunc

func (gomap *Map[K, V]) PopManyFunc(fn func(key K, value V) bool) *slice.Slice[V]

PopManyFunc removes key-value pairs from the map based on the provided condition function and returns the removed values in a slice. It takes a condition function as input and removes key-value pairs for which the function evaluates to true. It returns a slice containing the removed values.

// Create a new Map instance.
newMap := make(gomap.Map[string, int])
newMap.Add("apple", 5)
newMap.Add("orange", 10)

removedValues := newMap.PopManyFunc(func(key string, value int) bool {
	return value > 7  // Remove values greater than 7
})  // Returns a slice containing [10]

func (*Map[K, V]) PopOK

func (gomap *Map[K, V]) PopOK(key K) (V, bool)

PopOK removes a key-value pair from the map based on the provided key. It returns the removed value and a boolean indicating whether the key was found and removed successfully. If the key is present in the gomap, the corresponding value is returned, and the key-value pair is deleted. If the key is not found, it returns the zero value for the value type and false.

// Create a new Map instance.
newMap := make(gomap.Map[string, int])
newMap.Add("apple", 5)
removedValue, ok := newMap.PopOK("apple")  // Removes the key "apple" and returns its associated value 5, ok is true
removedValue, ok = newMap.PopOK("banana")   // Key "banana" not found, removedValue is 0 and ok is false

func (*Map[K, V]) ReplaceMany

func (gomap *Map[K, V]) ReplaceMany(fn func(key K, value V) (V, bool)) *Map[K, V]

ReplaceMany iterates over the key-value pairs in the map and applies the provided function to each pair. The function can modify the value and return a boolean indicating whether the update should be performed. If the function returns true, the key-value pair is updated in the same map with the modified value. If the function returns false, the key-value pair is not modified.

// Create a new Map instance.
newMap := make(gomap.Map[string, int])
newMap.Add("apple", 5)
newMap.Add("banana", 3)
newMap.Replace(func(key string, value int) (int, bool) {
    if key == "banana" {
        return value * 2, true // Modify the value for the "banana" key
    }
    return value, false // Leave other values unchanged
})
// newMap: {"apple": 5, "banana": 6}

func (*Map[K, V]) TakeFrom

func (gomap *Map[K, V]) TakeFrom(other *Map[K, V]) *Map[K, V]

TakeFrom transfers all key-value pairs from another map into the current gomap, emptying the other map. It takes another map as input and adds all key-value pairs from the other map to the current map.

// Create a new Map instance.
newMap1 := make(gomap.Map[string, int])
newMap1.Add("apple", 5)
// Create a new Map instance.
newMap2 := make(gomap.Map[string, int])
newMap2.Add("orange", 10)

newMap1.TakeFrom(newMap2)  // Transfers "orange": 10 from newMap2 to newMap1, leaving newMap2 empty

func (*Map[K, V]) Values

func (gomap *Map[K, V]) Values() *slice.Slice[V]

Values returns a slice containing all the values present in the map. It iterates over the map and collects all the values in the order of insertion.

// Create a new Map instance.
newMap := make(gomap.Map[string, int])
newMap.Add("apple", 5)
newMap.Add("orange", 10)
values := newMap.Values()  // Returns a slice containing [5, 10]

func (*Map[K, V]) ValuesFunc

func (gomap *Map[K, V]) ValuesFunc(fn func(key K, value V) bool) *slice.Slice[V]

ValuesFunc returns a slice containing values from the map that satisfy the given condition function. The condition function takes a key-value pair as input and returns true if the pair meets the condition, false otherwise. It iterates over the map and includes the values in the returned slice for which the condition function evaluates to true.

// Create a new Map instance.
newMap := make(gomap.Map[string, int])
newMap.Add("apple", 5)
newMap.Add("orange", 10)
values := newMap.ValuesFunc(func(key string, value int) bool {
	return value > 7  // Include values greater than 7 in the result
})  // Returns a slice containing [10]