box

README

box

box is a minimalist, type-safe utility package for Go that introduces generic container types to safely handle the presence or absence of data without relying on risky nil pointer dereferences.

By leveraging Go generics, box provides a clean, expressive API inspired by functional programming patterns like Optional and Maybe.

🚀 Quick Start

package main

import (
	"fmt"
	"github.com/atendi9/box"
)

func main() {
	// Creating a present value
	name := box.NewSome("Capivara")
	if name.IsPresent() {
		fmt.Println("Hello,", name.Get()) // Output: Hello, Capivara
	}

	// Creating an empty value
	empty := box.NewNone[string]()
	fmt.Println("Value:", empty.Get()) // Output: Value: "" (returns zero value safely)
}

Documentation

Index

• func All(conditions ...bool) bool
• func LazyTernary[T any](condition bool, fnTrue, fnFalse func() T) T
• func Ternary[T any](condition bool, resultTrue, resultFalse T) T
• func Unless(condition bool, fn func())
• func When(condition bool, fn func())
• type Atomic
  • func (s *Atomic[T]) CompareAndSwap(old, new T) (swapped bool)
  • func (s *Atomic[T]) Load() T
  • func (s *Atomic[T]) Store(val T)
  • func (s *Atomic[T]) Swap(new T) (old T)
• type Failure
  • func (f *Failure[T]) Error() error
  • func (f *Failure[T]) IsFailure() bool
  • func (f *Failure[T]) IsSuccess() bool
  • func (f *Failure[T]) Value() T
• type None
  • func (n *None[T]) Get() T
  • func (n *None[T]) IsEmpty() bool
  • func (n *None[T]) IsPresent() bool
• type Optional
  • func NewNone[T any]() Optional[T]
  • func NewSome[T any](value T) Optional[T]
• type Result
  • func NewFailure[T any](err error) Result[T]
  • func NewSuccess[T any](value T) Result[T]
• type Some
  • func (s *Some[T]) Get() T
  • func (s *Some[T]) IsEmpty() bool
  • func (s *Some[T]) IsPresent() bool
• type Success
  • func (s *Success[T]) Error() error
  • func (s *Success[T]) IsFailure() bool
  • func (s *Success[T]) IsSuccess() bool
  • func (s *Success[T]) Value() T
• type Void

Functions

func All

func All(conditions ...bool) bool

All returns true if all given boolean conditions evaluate to true.

func LazyTernary

func LazyTernary[T any](condition bool, fnTrue, fnFalse func() T) T

LazyTernary evaluates a boolean condition and executes one of two functions, returning its result.

func Ternary

func Ternary[T any](
	condition bool,
	resultTrue,
	resultFalse T,
) T

Ternary evaluates a boolean condition and returns one of two values.

func Unless

func Unless(condition bool, fn func())

Unless executes the provided function if the boolean condition evaluates to false.

func When

func When(condition bool, fn func())

When executes the provided function if the boolean condition evaluates to true.

Types

type Atomic

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

Atomic is a type-safe atomic value container. The zero value is the zero value of T. An Atomic must not be copied after first use.

func (*Atomic[T]) CompareAndSwap

func (s *Atomic[T]) CompareAndSwap(old, new T) (swapped bool)

CompareAndSwap executes the compare-and-swap operation for x. It returns true if the swap was successful (old matched the current value), false otherwise.

func (*Atomic[T]) Load

func (s *Atomic[T]) Load() T

Load atomically loads and returns the value stored in x. If the stored value is not of type T, returns the zero value of T.

func (*Atomic[T]) Store

func (s *Atomic[T]) Store(val T)

Store atomically stores val into x.

func (*Atomic[T]) Swap

func (s *Atomic[T]) Swap(new T) (old T)

Swap atomically stores new into x and returns the previous value. If the previous value is not of type T, returns the zero value of T.

type Failure

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

Failure struct represents a failed outcome wrapping an error within a Result container.

func (*Failure[T]) Error

func (f *Failure[T]) Error() error

Error returns the underlying wrapped error of Failure.

func (*Failure[T]) IsFailure

func (f *Failure[T]) IsFailure() bool

IsFailure always returns true for Failure.

func (*Failure[T]) IsSuccess

func (f *Failure[T]) IsSuccess() bool

IsSuccess always returns false for Failure.

func (*Failure[T]) Value

func (f *Failure[T]) Value() T

Value returns the zero value of type T since this represents a Failure.

type None

type None[T any] struct{}

None represents an Optional instance that does not contain any value.

func (*None[T]) Get

func (n *None[T]) Get() T

Get always returns the zero value of type T since None contains no value.

func (*None[T]) IsEmpty

func (n *None[T]) IsEmpty() bool

IsEmpty always returns true as None represents the absence of a value.

func (*None[T]) IsPresent

func (n *None[T]) IsPresent() bool

IsPresent always returns false as None never contains a value.

type Optional

type Optional[T any] interface {
	// IsPresent returns true if there is a value present, otherwise false.
	IsPresent() bool

	// IsEmpty returns true if there is no value present, otherwise false.
	IsEmpty() bool

	// Get returns the value if present. If no value is present, it returns the zero value of type T.
	Get() T
}

Optional represents a container object which may or may not contain a non-nil value. It provides a type-safe alternative to using nil pointers.

func NewNone

func NewNone[T any]() Optional[T]

NewNone creates and returns a new Optional representing an empty value. The returned instance is a pointer to None.

func NewSome

func NewSome[T any](value T) Optional[T]

NewSome creates and returns a new Optional containing the provided value. The returned instance is a pointer to Some.

type Result

type Result[T any] interface {
	// IsSuccess returns true if the operation completed successfully, otherwise false.
	IsSuccess() bool

	// IsFailure returns true if the operation failed with an error, otherwise false.
	IsFailure() bool

	// Value returns the success value if present, or the zero value of type T.
	Value() T

	// Error returns the underlying error if it failed, or nil.
	Error() error
}

Result represents the outcome of an operation that can either succeed with a value of type T or fail with an error. It wraps the standard built-in error type.

func NewFailure

func NewFailure[T any](err error) Result[T]

NewFailure creates and returns a new failed Result containing the provided error.

func NewSuccess

func NewSuccess[T any](value T) Result[T]

NewSuccess creates and returns a new successful Result containing the provided value.

type Some

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

Some represents an Optional instance that contains a value.

func (*Some[T]) Get

func (s *Some[T]) Get() T

Get returns the underlying value. If the receiver is nil, it returns the zero value of type T.

func (*Some[T]) IsEmpty

func (s *Some[T]) IsEmpty() bool

IsEmpty returns true if the receiver is nil.

func (*Some[T]) IsPresent

func (s *Some[T]) IsPresent() bool

IsPresent returns true if the receiver is not nil.

type Success

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

Success struct represents a successful outcome within a Result container.

func (*Success[T]) Error

func (s *Success[T]) Error() error

Error always returns nil for Success.

func (*Success[T]) IsFailure

func (s *Success[T]) IsFailure() bool

IsFailure always returns false for Success.

func (*Success[T]) IsSuccess

func (s *Success[T]) IsSuccess() bool

IsSuccess always returns true for Success.

func (*Success[T]) Value

func (s *Success[T]) Value() T

Value returns the inner wrapped value of Success.

type Void

type Void = struct{}

Void represents an empty structure used to signal the absence of data. It is commonly used for set implementations or synchronization signals.

var NULL Void

NULL is a globally shared instance of Void.