sortedlists

README

SortedLists

• SortedLists
  • Purpose
  • Installation
  • Usage
  • Libraries
  • Licence

---

Purpose

//TODO

Installation

You can use Go to install this package for you:

go get -u github.com/mwat56/sortedlists

Usage

//TODO

Libraries

The following external libraries were used building sortedlists:

• [None]

Licence

    Copyright © 2024 M.Watermann, 10247 Berlin, Germany
                    All rights reserved
                EMail : <support@mwat.de>

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This software is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

You should have received a copy of the GNU General Public License along with this program. If not, see the GNU General Public License for details.

---

Documentation

Overview

Package sortedlists implements a sorted slice and a sorted map.

Copyright © 2024 M.Watermann, 10247 Berlin, Germany
                All rights reserved
            EMail : <support@mwat.de>

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This software is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

You should have received a copy of the GNU General Public License along with this program. If not, see the [GNU General Public License](http://www.gnu.org/licenses/gpl.html) for details.

Copyright © 2023, 2024 M.Watermann, 10247 Berlin, Germany

	All rights reserved
EMail : <support@mwat.de>

Copyright © 2024 M.Watermann, 10247 Berlin, Germany

	All rights reserved
EMail : <support@mwat.de>

Index

• type TSortedMap
  • func NewMap[K cmp.Ordered, V comparable](aSafe bool) *TSortedMap[K, V]
  • func (sm *TSortedMap[K, V]) Clear() *TSortedMap[K, V]
  • func (sm *TSortedMap[K, V]) Delete(aKey K) bool
  • func (sm *TSortedMap[K, V]) Equals(aMap *TSortedMap[K, V]) bool
  • func (sm *TSortedMap[K, V]) FindIndex(aValue V) []K
  • func (sm *TSortedMap[K, V]) Get(aKey K) (V, bool)
  • func (sm *TSortedMap[K, V]) Insert(aKey K, aValue V) bool
  • func (sm *TSortedMap[K, V]) IsSafe() bool
  • func (sm *TSortedMap[K, V]) Iterate(aFunc func(K, V)) *TSortedMap[K, V]
  • func (sm *TSortedMap[K, V]) Iterator() func() (K, V, bool)
  • func (sm *TSortedMap[K, V]) Keys() []K
  • func (sm *TSortedMap[K, V]) Rename(aOldKey, aNewKey K) bool
  • func (sm *TSortedMap[K, V]) String() string
• type TSortedSlice
  • func NewSlice[T cmp.Ordered](aList []T, aSafe bool) *TSortedSlice[T]
  • func (ss *TSortedSlice[T]) Clear() *TSortedSlice[T]
  • func (ss *TSortedSlice[T]) Data() []T
  • func (ss *TSortedSlice[T]) Delete(aElement T) bool
  • func (ss *TSortedSlice[T]) Equals(aList *TSortedSlice[T]) bool
  • func (ss *TSortedSlice[T]) FindIndex(aElement T) int
  • func (ss *TSortedSlice[T]) Get(aIndex int) (T, bool)
  • func (ss *TSortedSlice[T]) Insert(aElement T) bool
  • func (ss *TSortedSlice[T]) IsSafe() bool
  • func (ss *TSortedSlice[T]) Rename(aOldValue, aNewValue T) bool
  • func (ss *TSortedSlice[T]) String() string

Types

type TSortedMap

type TSortedMap[K cmp.Ordered, V comparable] struct {
	// contains filtered or unexported fields
}

`TSortedMap` is a generic type that accepts two type parameters: - K for the key type (which must be cmp.Ordered) - V for the value type

The `cmp.Ordered` interface is defined as:

~int | ~int8 | ~int16 | ~int32 | ~int64 |
	~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 | ~uintptr |
	~float32 | ~float64 |
	~string

`comparable` is an interface that is implemented by all comparable types (booleans, numbers, strings, pointers, channels, arrays of comparable types, structs whose fields are all comparable types).

All methods are optionally thread-safe and can be called concurrently.

func NewMap

func NewMap[K cmp.Ordered, V comparable](aSafe bool) *TSortedMap[K, V]

`NewMap()` creates a new instance of `TSortedMap` with the specified key and value types.

The returned map is initially empty.

Parameters:

• `K`: The type of the keys in the sorted map.
• `V`: The type of the values in the sorted map.
• `aSafe`: Flag to decide whether the returned map should be thread safe, i.e. use a `sync.RWMutex` in all methods.

Returns: - `*TSortedMap[K, V]`: A pointer to a new instance with the given key and value types.

func (*TSortedMap[K, V]) Clear

func (sm *TSortedMap[K, V]) Clear() *TSortedMap[K, V]

`Clear()` empties the internal data structures: all map entries are removed.

Returns: - `*TSortedMap`: The cleared hash map.

func (*TSortedMap[K, V]) Delete

func (sm *TSortedMap[K, V]) Delete(aKey K) bool

`Delete()` removes a key/value pair from the map.

Parameters: - `aKey`: The key of the entry to be deleted.

Returns: - `bool`: `true` if `aKey` was removed, or `false` otherwise.

func (*TSortedMap[K, V]) Equals

func (sm *TSortedMap[K, V]) Equals(aMap *TSortedMap[K, V]) bool

func (*TSortedMap[K, V]) FindIndex

func (sm *TSortedMap[K, V]) FindIndex(aValue V) []K

`FindIndex()` returns a slice of keys that have the given value.

Parameters: - `aValue`: The element to look up.

Returns: - `[]K`: The index of `aID` in the list.

func (*TSortedMap[K, V]) Get

func (sm *TSortedMap[K, V]) Get(aKey K) (V, bool)

`Get()` retrieves a value by its key from the SortedMap

Parameters: - `aKey`: The key of the entry to be retrieved.

Returns: - `V`: The value associated with the `aKey`. - `bool`: An indication whether the key was found in the map.

func (*TSortedMap[K, V]) Insert

func (sm *TSortedMap[K, V]) Insert(aKey K, aValue V) bool

`Insert()` adds or updates a key/value pair in the sorted map.

Parameters: - `aKey`: The key of the entry to be added or updated. - `aValue`: The value to be associated with the key.

Returns: - `bool`: `true` if `aID` was inserted, or `false` otherwise.

func (*TSortedMap[K, V]) IsSafe

func (sm *TSortedMap[K, V]) IsSafe() bool

`IsSafe()` returns whether the current map is thread-safe.

A `TSortedMap` instance is thread-safe if it was created with the `aSafe` flag set to `true` when calling the constructor function `NewMap()`. In a thread-safe instance, all methods can be called concurrently without causing data corruption or race conditions.

Returns:

• bool: A boolean value indicating whether the current map is thread-safe.

func (*TSortedMap[K, V]) Iterate

func (sm *TSortedMap[K, V]) Iterate(aFunc func(K, V)) *TSortedMap[K, V]

`Iterate()` allows iteration over the map in sorted key order.

Parameters:

• `aFunc`: A function that takes a key and its associated value as arguments and performs some operation on them.

Returns:

• `*TSortedMap[K, V]`: A pointer to the same SortedMap instance,

allowing method chaining.

func (*TSortedMap[K, V]) Iterator

func (sm *TSortedMap[K, V]) Iterator() func() (K, V, bool)

func (*TSortedMap[K, V]) Keys

func (sm *TSortedMap[K, V]) Keys() []K

`Keys()` returns a slice of all keys in sorted order

This method returns a slice of all keys in the map in sorted order.

Returns: - `[]K`: A slice of keys in the sorted map.

func (*TSortedMap[K, V]) Rename

func (sm *TSortedMap[K, V]) Rename(aOldKey, aNewKey K) bool

`Rename()` changes the key of an existing entry without affecting its value.

If `aOldKey` equals `aNewKey`, or aOldKey` doesn't exist then they are silently ignored (i.e. this method does nothing), returning `false`.

If `aNewKey` already exists, it is ignored and the method returns `false`.

Parameters: - `aOldKey`: the key to be replaced in this list. - `aNewKey`: The replacement key in this list.

Returns: - `bool`: `true` if the the renaming was successful, or `false` otherwise.

func (*TSortedMap[K, V]) String

func (sm *TSortedMap[K, V]) String() string

type TSortedSlice

type TSortedSlice[T cmp.Ordered] struct {
	// contains filtered or unexported fields
}

`TSortedSlice` represents a sorted slice of any ordered type.

This is a generic type that accepts a type parameter: - T for the ordered value type.

The `Ordered` interface is defined as:

~int | ~int8 | ~int16 | ~int32 | ~int64 |
	~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 | ~uintptr |
	~float32 | ~float64 |
	~string

All methods are optionally thread-safe and can be called concurrently.

func NewSlice

func NewSlice[T cmp.Ordered](aList []T, aSafe bool) *TSortedSlice[T]

`NewSlice()` creates a new `TSortedSlice`.

If the given `aList` is empty the initial capacity of the underlying list is set to 32 to optimise memory usage.

Parameters: - `aList`: The slice to use with the sorted slice. - `aSafe`: Flag to decide whether the returned map should be thread safe, i.e. use a `sync.RWMutex` in all methods.

Returns: - `*TSortedSlice[T]`: A pointer to the newly created instance.

func (*TSortedSlice[T]) Clear

func (ss *TSortedSlice[T]) Clear() *TSortedSlice[T]

`Clear()` removes all entries in this list.

Returns: - `*TSortedSlice[T]`: The cleared list instance.

func (*TSortedSlice[T]) Data

func (ss *TSortedSlice[T]) Data() []T

`Data()` returns the underlying data of the sorted slice.

Returns: - `[]T`: The underlying data of the sorted slice.

func (*TSortedSlice[T]) Delete

func (ss *TSortedSlice[T]) Delete(aElement T) bool

`Delete()` removes an element from the sorted slice.

Parameters: - `aElement`: The element to remove from the list.

Returns: - `bool`: `true` if `aElement` was removed, or `false` otherwise.

func (*TSortedSlice[T]) Equals

func (ss *TSortedSlice[T]) Equals(aList *TSortedSlice[T]) bool

`Equals()` checks if the current sorted slice is equal to another sorted slice.

The method compares the elements of the current sorted slice with the elements of the given sorted slice. It returns `true` if both slices contain the same elements in the same order, or `false` otherwise.

If the slices are thread-safe, the method acquires the respective read locks before performing the comparison.

Parameters:

• `aList`: The sorted slice to compare with the current slice.

Returns:

• `bool`: An indicator for whether the current slice is equal to `aList`.

func (*TSortedSlice[T]) FindIndex

func (ss *TSortedSlice[T]) FindIndex(aElement T) int

`FindIndex()` returns the list index of `aElement`.

If the `aElement` is not found, the method returns -1.

Parameters: - `aElement`: The list element to look up.

Returns: - `int`: The index of `aID` in the list.

func (*TSortedSlice[T]) Get

func (ss *TSortedSlice[T]) Get(aIndex int) (T, bool)

`Get()` retrieves a value by its list index from the sorted slice.

Parameters: - `aIndex`: The list index to use for returning the list element.

Returns: - `T`: The value associated with the `aIndex`. - `bool`: An indication whether the index was found in the list.

func (*TSortedSlice[T]) Insert

func (ss *TSortedSlice[T]) Insert(aElement T) bool

`Insert()` adds an element to the sorted slice while maintaining order.

Parameters: - `aElement` The element to insert to the list.

Returns: - `bool`: `true` if `aElement` was inserted, or `false` otherwise.

func (*TSortedSlice[T]) IsSafe

func (ss *TSortedSlice[T]) IsSafe() bool

`IsSafe()` returns whether the current slice is thread-safe.

A `TSortedSlice` instance is thread-safe if it was created with the `aSafe` flag set to `true` when calling the constructor function `NewSlice()`. In a thread-safe instance, all methods can be called concurrently without causing data corruption or race conditions.

Returns:

• bool: An indicator for whether the current slice is thread-safe.

func (*TSortedSlice[T]) Rename

func (ss *TSortedSlice[T]) Rename(aOldValue, aNewValue T) bool

Rename changes an element in the sorted slice and maintains order.

func (*TSortedSlice[T]) String

func (ss *TSortedSlice[T]) String() string

`String()` implements the `fmt.Stringer` interface.

For each element, the method appends the element's string representation while elements are separated by ", ".

Returns: - `string`: The list's contents as a string.