sx

package module
v1.0.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 21, 2023 License: 0BSD Imports: 10 Imported by: 0

README

sx - Simple Extensions for the Go Programming Language

Go Report Card

License

Everything in this repository is provided under the 0BSD License (see: spdx.org), a public domain equivalent license
(when in doubt, please contact your lawyer)

$~$

About

Unfortunately, the Go standard library does not provide generic types.
So I wrote this library to make my life easier - and maybe yours, too.
I hope you like it 🙂

$~$

Features:

  • Standard Containers (Array, HashMap, Optional)
  • Iterators (extensible)
  • Result Type (a bit 'rusticious' - similar to std::expected)
  • Exceptions (based on panic/recover)
  • ... and some other small helpers

$~$

Quality:

  • high quality library with 100% test coverage
  • dependency free and non-invasive
  • minimalistic, but 'all-in-one' solution
  • written in pure Go
  • 0BSD licence, so you don't have to give credit or carry around copyright notices
  • No legacy stuff - you need an up-to-date Go version (1.20+)

$~$

$~$

Usage / Examples

$~$

Basic Usage
// tldr; just use the library as a module (legacy non-module usage is not supported)
// 1. include the header for the library
// 2. update/check your go.mod file
// 3. run "go mod tidy" to update your go.sum file
// 4. check your go.sum file for the correct version, just in case

// do your package thing
package main

// import the library
import (
	"github.com/ZeroBsd/sx"
)

// enjoy
func Main() {
	sx.PrintLn("Hello, ", "World")
}
Arrays / Maps
var array1 = sx.NewArray[int]()       // create dynamic array using a generic value type
var array2 = sx.NewArrayFrom(1, 2, 3) // same as above, but infer the value type from the values
array1.PushArray(array2)              // add all items from array2 to array1
array1.Push(array2.SubSlice()...)     // same
array1.Push(4)                        // add another value

// iterate through all key/value pairs. This works for every array and map
for it := array1.NewIterator(); it.Ok(); it.Next() {
	sx.PrintAnyLn("Key: '", it.Key(), "' ; Value: '", it.Value(), "'")
}

// arrays are maps - they satisfy the 'Map' interface
var myMap sx.Map[int, int] = array1

// replace the entry at index 0
// since this is actually an array, the index must exist
// for real maps, this restriction is not present
if myMap.Has(0) {
	myMap.Put(0, 42)
}
sx.ThrowIf(myMap.Get(0).Value() != 42, "Oh no, the value is not 42!")

// the iterator is part of the 'Map' interface
// when iterating over a real map, the order is undefined. For arrays, iteration is ordered
for it := myMap.NewIterator(); it.Ok(); it.Next() {
	sx.PrintAnyLn("Key: '", it.Key(), "' ; Value: '", it.Value(), "'")
}
Error Handling and Exceptions
// this function returns a result which contains either the value (of type int) or an error
func playThrowAndCatch(throws bool) (result sx.Result[int]) {

	// provide an error handler in case something goes wrong
	// !!! Important: don't forget the 'defer' !!!
	defer sx.Catch(func(err error) {

		// we print the exception message here
		// this may be ok, since we do not re-throw (log-and-throw-antipattern)
		sx.PrintStdErrLn(err.Error())

		// we transform the exception (panic) to a valid result (that contains the error)
		// be aware that we cannot use 'return' here, so we make use of the named return value
		result = sx.NewResultFromError[int](err)
	})

	// throws, if the input variable (bool) was true. The text will be encapsulated in an error
	sx.ThrowIf(throws, "This is thrown as an error if throws is true. Internally, this panics with an error")

	// if the above didn't throw, we return a valid number. In this case, the type argument is inferred
	return sx.NewResultFrom(42)
}

Documentation

Overview

SPDX-License-Identifier: 0BSD

SPDX-License-Identifier: 0BSD

SPDX-License-Identifier: 0BSD

SPDX-License-Identifier: 0BSD

SPDX-License-Identifier: 0BSD

SPDX-License-Identifier: 0BSD

SPDX-License-Identifier: 0BSD

SPDX-License-Identifier: 0BSD

SPDX-License-Identifier: 0BSD

SPDX-License-Identifier: 0BSD

SPDX-License-Identifier: 0BSD

SPDX-License-Identifier: 0BSD

SPDX-License-Identifier: 0BSD

SPDX-License-Identifier: 0BSD

SPDX-License-Identifier: 0BSD

SPDX-License-Identifier: 0BSD

SPDX-License-Identifier: 0BSD

Index

Constants

View Source 
const FilePathSeparator = string(os.PathSeparator)
View Source 
const RunningOnWindows = runtime.GOOS == "windows"

Variables

This section is empty.

Functions

func Catch 

func Catch(handler ...func(error))

Catches errors thrown by "Throw" or "ThrowIf", recovers the panic Needs to be called before throwing errors Only handles errors. If you throw/panic something else, you need to provide a custom recover function

func ContainsValue 

func ContainsValue[K comparable, V comparable](m Map[K, V], value V) bool

Checks if a sx.Map or sx.Array contains a certain value (for keys we can just use map.Has(key))

func Debug 

func Debug(values ...string)

Print debug messages will not print by default, please call "SetDebugOn" first

func DebugAny added in v1.0.2 

func DebugAny(values ...any)

Print debug messages will not print by default, please call "SetDebugOn" first

func DebugIsActive added in v1.0.2 

func DebugIsActive() bool

func DebugPop added in v1.0.2 

func DebugPop()

func DebugPushOff added in v1.0.2 

func DebugPushOff()

func DebugPushOn added in v1.0.2 

func DebugPushOn()

func DebugSetOff added in v1.0.2 

func DebugSetOff()

func DebugSetOn added in v1.0.2 

func DebugSetOn()

func FileBaseName added in v1.0.2 

func FileBaseName(fileNameOrPath string) string

func FileExtension added in v1.0.2 

func FileExtension(fileNameOrPath string) string

func FileWithoutExtension added in v1.0.2 

func FileWithoutExtension(fileNameOrPath string) string

func Print added in v1.0.2 

func Print(values ...string)

func PrintAny added in v1.0.2 

func PrintAny(values ...any)

func PrintAnyLn added in v1.0.2 

func PrintAnyLn(values ...any)

func PrintAnyStdErr added in v1.0.2 

func PrintAnyStdErr(values ...any)

func PrintAnyStdErrLn added in v1.0.2 

func PrintAnyStdErrLn(values ...any)

func PrintLn added in v1.0.2 

func PrintLn(values ...string)

func PrintStdErr added in v1.0.2 

func PrintStdErr(values ...string)

func PrintStdErrLn added in v1.0.2 

func PrintStdErrLn(values ...string)

func ReflectFunctionName 

func ReflectFunctionName(optFuncLevel ...int) (functionName string)

Shows function name of the caller of the current function

returns empty string when in "main"

optFuncLevel 0 (default) means current Function name

optFuncLevel 1 (default) means caller of current function

optFuncLevel 2+ (default) means caller of caller of current function...

func ReflectType added in v1.0.2 

func ReflectType[T any](instances ...T) reflect.Type

Returns the reflect.Type for an instance of a type.

Also works without an actual instance by passing 'nil'.

func ReflectTypeName added in v1.0.2 

func ReflectTypeName[T any](instance ...T) string

func Str 

func Str(values ...any) string

Concatenates values without adding any extra (white-)spaces

func StrCat added in v1.0.2 

func StrCat(stringsToJoin ...string) string

Concatenates strings without adding any extra (white-)spaces

func StrJoin added in v1.0.2 

func StrJoin(separator string, stringsToJoin ...string) string

Joins strings using a separator, but without adding any extra (white-)spaces

func Throw 

func Throw(errorMessages ...string)

Throws an error by panic-ing

func ThrowIf 

func ThrowIf(condition bool, errorMessages ...string)

Throws an error by panic-ing iff the condition is true

func ThrowIfError added in v1.0.2 

func ThrowIfError(err error)

Types

type Array 

type Array[V any] interface {
	Iterable[int, V]
	Stack[V]
	Map[int, V]
	Compact()                             // Copies Array and removes excessive memory
	SubSlice(fromIndexToIndex ...int) []V // Returns a go slice
}

func FindAll 

func FindAll[K comparable, V any](m Map[K, V], condition func(key K, value V) bool) Array[Pair[K, V]]

Finds all entries in sx.Map or sx.Array where the condition is true and returns a list of key/value pairs

func MapValues added in v1.0.3 

func MapValues[K any, V any, TO any](fromIterator Iterator[K, V], mapperFunc func(key K, value V) Optional[TO]) Array[TO]

Maps the Iterator Values to a new type

Can return

func NewArray 

func NewArray[V any](capacity ...int) Array[V]

func NewArrayFrom 

func NewArrayFrom[V any](items ...V) Array[V]

func RemoveAll 

func RemoveAll[V any](arr Array[V], condition func(value V) bool) Array[V]

Copies sx.Array with all values removed where the condition is true and returns the copy

func TypeCastArray 

func TypeCastArray[TO any, FROM any](fromArray Array[FROM]) Array[TO]

Create new Array with TypeCast-ed items

Best effort, only adds items that can be casted to the new array

type Container 

type Container interface {
	Length() int
	IsEmpty() bool
}

type Dir added in v1.0.2 

type Dir string

func DirRoot added in v1.0.2 

func DirRoot() Dir

func DirTemp added in v1.0.2 

func DirTemp() Dir

func NewDir added in v1.0.2 

func NewDir(pathParts ...string) Dir

Create a Dir from its parts It is assumed that there are no FilePathSeparators within the parts Directories always end with the FilePathSeparator

func NewDirFromString added in v1.0.2 

func NewDirFromString(path string) Dir

Create a Dir from a path/string Directories always end with the FilePathSeparator

func (Dir) Cd added in v1.0.2 

func (dir Dir) Cd(folderName string) Result[Dir]

Descends into a folder. Folder must exist.

func (Dir) CreateDir added in v1.0.2 

func (dir Dir) CreateDir(folderName string) Result[Dir]

func (Dir) Exists added in v1.0.2 

func (dir Dir) Exists() bool

func (Dir) HasParent added in v1.0.2 

func (dir Dir) HasParent() bool

func (Dir) IsDirectory added in v1.0.2 

func (dir Dir) IsDirectory(fileName string) bool

func (Dir) IsFile added in v1.0.2 

func (dir Dir) IsFile(fileName string) bool
func (dir Dir) IsSymlink(fileName string) bool

func (Dir) NewIterator added in v1.0.2 

func (dir Dir) NewIterator() Iterator[int, string]

func (Dir) Parent added in v1.0.2 

func (dir Dir) Parent() Result[Dir]

func (Dir) ReadAllBytes added in v1.0.2 

func (dir Dir) ReadAllBytes(fromFileName string) Result[[]byte]

func (Dir) ReadAllText added in v1.0.2 

func (dir Dir) ReadAllText(fromFileName string) Result[string]

Reads all the text from a file, newlines are always converted to '\n'

func (Dir) String added in v1.0.2 

func (dir Dir) String() string

func (Dir) WriteAllText added in v1.0.2 

func (dir Dir) WriteAllText(toFileName string, text string) error

Write all the text to a file, no modifications

type DomVisitor added in v1.0.3 

type DomVisitor[Context any] struct {
	Context     Context
	BeforeVisit func(context Context, domTreeNode any) (continueVisit bool)
	AfterVisit  func(context Context, domTreeNode any)
}

func NewDomVisitor added in v1.0.3 

func NewDomVisitor[Context any](ctx Context) (visitor DomVisitor[Context])

func (DomVisitor[Context]) VisitRecursively added in v1.0.3 

func (visitor DomVisitor[Context]) VisitRecursively(domTreeNode any)

type Iterable 

type Iterable[K any, V any] interface {
	NewIterator() Iterator[K, V]
}

type Iterator 

type Iterator[K any, V any] interface {
	Ok() bool // Checks if iterator is valid and can return a key or a value. For empty containers, this is false after iterator creation.
	Key() K   // Returns the key of the current item
	Value() V // Returns the value of the current item
	Next()    // Finds the next item. If it reached the end, Ok() will return false after this call
}

func NewMapIterator added in v1.0.3 

func NewMapIterator[K comparable, V any](m map[K]V) Iterator[K, V]

type Map 

type Map[K comparable, V any] interface {
	Set[K, V]
	Get(K) Result[V] // Returns Value for the key (if present)
}

func NewHashMap 

func NewHashMap[K comparable, V any]() Map[K, V]

func NewHashMapFrom 

func NewHashMapFrom[K comparable, V any](values map[K]V) Map[K, V]

func NewMap 

func NewMap[K comparable, V any]() Map[K, V]

func NewMapFrom 

func NewMapFrom[K comparable, V any](values map[K]V) Map[K, V]

func NewSet added in v1.0.3 

func NewSet[K comparable]() Map[K, struct{}]

func NewSetFrom 

func NewSetFrom[K comparable](values ...K) Map[K, struct{}]

type Optional 

type Optional[T any] struct {
	// contains filtered or unexported fields
}

func FindFirstWhere 

func FindFirstWhere[K comparable, V any](m Map[K, V], condition func(key K, value V) bool) Optional[Pair[K, V]]

Finds first entry in sx.Map or sx.Array where the condition is true and returns a key/value pair

func NewOptional 

func NewOptional[V any]() Optional[V]

func NewOptionalFrom 

func NewOptionalFrom[V any](value V) Optional[V]

func (Optional[T]) IsEmpty 

func (opt Optional[T]) IsEmpty() bool

func (Optional[T]) Length 

func (opt Optional[T]) Length() int

func (Optional[T]) NewIterator 

func (opt Optional[T]) NewIterator() Iterator[int, T]

func (Optional[T]) Ok 

func (opt Optional[T]) Ok() bool

func (Optional[T]) Value 

func (opt Optional[T]) Value() T

func (Optional[T]) ValueOr 

func (opt Optional[T]) ValueOr(defaultValue T) T

func (Optional[T]) ValueOrDefault 

func (opt Optional[T]) ValueOrDefault() (value T)

type Pair 

type Pair[K any, V any] struct {
	Key   K
	Value V
}

func NewPair 

func NewPair[K any, V any](key K, value V) Pair[K, V]

type Result 

type Result[T any] struct {
	// contains filtered or unexported fields
}

func DirUserHome added in v1.0.2 

func DirUserHome() Result[Dir]

func FromJson added in v1.0.3 

func FromJson[T any](jsonString string) Result[T]

Tries to convert a json string into the specified object

func FromJsonInterface added in v1.0.3 

func FromJsonInterface[T any](jsonString string, object *T) Result[T]

func MkDirAndPath added in v1.0.2 

func MkDirAndPath(fullPathString string) Result[Dir]

Returns a Dir from a string, creates a new directory if needed (including all parents)

func NewResultError 

func NewResultError[V any](errorMessageParts ...string) Result[V]

func NewResultFrom 

func NewResultFrom[V any](value V) Result[V]

func NewResultFromError added in v1.0.2 

func NewResultFromError[V any](err error) Result[V]

func String2Bool 

func String2Bool(s string) Result[bool]

func String2Float 

func String2Float(s string) Result[float64]

func String2Int 

func String2Int(s string) Result[int64]

func ToJson added in v1.0.3 

func ToJson(object any) Result[string]

Tries to convert object to a compact/dense json string

func ToJsonPretty added in v1.0.3 

func ToJsonPretty(object any, indentationString string) Result[string]

Tries to convert object to a pretty-printed json string

recommended indentationStrings are "\t" or multiple spaces

func TypeCast 

func TypeCast[T any](it any) Result[T]

Typecast with Result, allowed to fail

func (Result[T]) Error 

func (r Result[T]) Error() string

func (Result[T]) Ok 

func (r Result[T]) Ok() bool

func (Result[T]) Value 

func (r Result[T]) Value() T

func (Result[T]) ValueIsOptional added in v1.0.2 

func (r Result[T]) ValueIsOptional() Optional[T]

func (Result[T]) ValueOr 

func (r Result[T]) ValueOr(defaultValue T) T

func (Result[T]) ValueOrInit added in v1.0.2 

func (r Result[T]) ValueOrInit() (value T)

func (Result[T]) ValueOrThrow added in v1.0.2 

func (r Result[T]) ValueOrThrow(errorMessage string) T

type Set added in v1.0.3 

type Set[K comparable, V any] interface {
	Container
	Iterable[K, V]
	Has(K) bool    // Checks if key is present
	Put(K, V) bool // Sets value for a key
	Drop(K) bool   // Removes a key and its value
}

type SliceIterator added in v1.0.3 

type SliceIterator[K int, V any] struct {
	// contains filtered or unexported fields
}

func NewSliceIterator added in v1.0.3 

func NewSliceIterator[V any](slice []V) SliceIterator[int, V]

func (SliceIterator[int, V]) Key added in v1.0.3 

func (it SliceIterator[int, V]) Key() int

func (*SliceIterator[int, V]) Next added in v1.0.3 

func (it *SliceIterator[int, V]) Next()

func (SliceIterator[int, V]) Ok added in v1.0.3 

func (it SliceIterator[int, V]) Ok() bool

func (SliceIterator[int, V]) SetValue added in v1.0.3 

func (it SliceIterator[int, V]) SetValue(v V)

func (SliceIterator[int, V]) Value added in v1.0.3 

func (it SliceIterator[int, V]) Value() V

type Stack 

type Stack[V any] interface {
	Container
	Push(value ...V)             // Inserts all values at the end
	PushArray(otherVec Array[V]) // Inserts all values of an sx.Array at the end
	Pop() (value Result[V])      // Removes and returns last value (if present)
	Peek() (value Result[V])     // Returns last value (if present)
}

func NewStack 

func NewStack[V any](capacity ...int) Stack[V]

type StringBuilder added in v1.0.2 

type StringBuilder struct {
	strings.Builder
}

func NewStringBuilder added in v1.0.2 

func NewStringBuilder() *StringBuilder

func (*StringBuilder) WriteAny added in v1.0.2 

func (sb *StringBuilder) WriteAny(values ...any) *StringBuilder

func (*StringBuilder) WriteStrings added in v1.0.2 

func (sb *StringBuilder) WriteStrings(values ...string) *StringBuilder

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.