common

func IsoId ¶

func IsoId[S any]() Iso[S, S]

IsoId returns an identity isomorphism that performs no transformation. Both Get and ReverseGet are the identity function.

Type Parameters:

• S: The type for both source and target

Returns:

• An Iso[S, S] where Get and ReverseGet are both identity functions

Example:

idIso := IsoId[int]()
value := idIso.Get(42)        // 42
same := idIso.ReverseGet(42)  // 42

Use cases:

• As a starting point for isomorphism composition
• When you need an isomorphism but don't want to transform the value
• In generic code that requires an isomorphism parameter

func IsoReverse ¶

func IsoReverse[S, A any](sa Iso[S, A]) Iso[A, S]

IsoReverse swaps the direction of an isomorphism. Given Iso[S, A], creates Iso[A, S] where Get and ReverseGet are swapped.

Type Parameters:

• S: The original source type (becomes target)
• A: The original target type (becomes source)

Parameters:

• sa: The isomorphism to reverse

Returns:

• An Iso[A, S] with Get and ReverseGet swapped

Example:

celsiusToFahrenheit := MakeIso(
    func(c float64) float64 { return c*9/5 + 32 },
    func(f float64) float64 { return (f - 32) * 5 / 9 },
)

// IsoReverse to get Fahrenheit to Celsius
fahrenheitToCelsius := IsoReverse(celsiusToFahrenheit)

celsius := fahrenheitToCelsius.Get(68.0)        // 20.0
fahrenheit := fahrenheitToCelsius.ReverseGet(20.0) // 68.0

func MakeIso ¶

func MakeIso[S, A any](get func(S) A, reverse func(A) S) Iso[S, A]

MakeIso constructs an isomorphism from two functions. The functions should be inverses of each other to satisfy the isomorphism laws.

Type Parameters:

• S: The source type
• A: The target type

Parameters:

• get: Function to convert from S to A
• reverse: Function to convert from A to S (inverse of get)

Returns:

• An Iso[S, A] that uses the provided functions

Example:

// Create an isomorphism between string and []byte
stringBytesIso := MakeIso(
    func(s string) []byte { return []byte(s) },
    func(b []byte) string { return string(b) },
)

bytes := stringBytesIso.Get("hello")           // []byte("hello")
str := stringBytesIso.ReverseGet([]byte("hi")) // "hi"

func IsoAsLens ¶

func IsoAsLens[S, A any](sa Iso[S, A]) Lens[S, A]

IsoAsLens converts an Iso[S, A] into a Lens[S, A].

The resulting lens uses the iso's Get as its getter and its ReverseGet as its setter. Because an isomorphism is total and invertible, Set always replaces the focused value by applying ReverseGet — the original S is discarded.

Type Parameters:

• S: The source type of the isomorphism and of the resulting lens
• A: The target type of the isomorphism and the focus type of the resulting lens

Parameters:

• sa: The isomorphism to convert

Returns:

• Lens[S, A]: a lens whose Get is sa.Get and whose Set is sa.ReverseGet

See Also:

• IsoAsLensRef: the pointer-receiver variant for Iso[*S, A]

func LensId ¶

func LensId[S any]() Lens[S, S]

LensId returns an identity Lens that focuses on the entire structure.

The identity lens is useful as a starting point for lens composition or when you need a lens that doesn't actually focus on a subpart. Get returns the structure unchanged, and Set replaces the entire structure.

Type Parameters:

• S: The structure type

Returns:

• A Lens[S, S] where both source and focus are the same type

Example:

type Person struct {
    Name string
    Age  int
}

idLens := lens.LensId[Person]()
person := Person{Name: "Alice", Age: 30}

same := idLens.Get(person)  // Returns person unchanged
replaced := idLens.Set(Person{Name: "Bob", Age: 25})(person)
// replaced is Person{Name: "Bob", Age: 25}

func LensIdRef ¶

func LensIdRef[S any]() Lens[*S, *S]

LensIdRef returns an identity Lens for pointer-based structures.

This is the pointer version of LensId. It focuses on the entire pointer structure, with automatic copying to ensure immutability.

Type Parameters:

• S: The structure type (will be used as *S)

Returns:

• A Lens[*S, *S] where both source and focus are pointers to the same type

Example:

idLens := lens.LensIdRef[Person]()
person := &Person{Name: "Alice", Age: 30}

same := idLens.Get(person)  // Returns person pointer
replaced := idLens.Set(&Person{Name: "Bob", Age: 25})(person)
// person.Name is still "Alice", replaced is a new pointer

func MakeLens ¶

func MakeLens[GET ~func(S) A, SET ~func(S, A) S, S, A any](get GET, set SET) Lens[S, A]

MakeLens creates a Lens based on a getter and a setter F.

The setter must create a (shallow) copy of the data structure. This happens automatically when the data is passed by value. For pointer-based structures, use MakeLensRef instead. For other reference types (slices, maps), ensure the setter creates a copy.

Type Parameters:

• GET: Getter function type (S → A)
• SET: Setter function type (S, A → S)
• S: Source structure type
• A: Focus/field type

Parameters:

• get: Function to extract value A from structure S
• set: Function to update value A in structure S, returning a new S

Returns:

• A Lens[S, A] that can get and set values immutably

Example:

type Person struct {
    Name string
    Age  int
}

nameLens := lens.MakeLens(
    func(p Person) string { return p.Name },
    func(p Person, name string) Person {
        p.Name = name
        return p
    },
)

person := Person{Name: "Alice", Age: 30}
name := nameLens.Get(person)           // "Alice"
updated := nameLens.Set("Bob")(person) // Person{Name: "Bob", Age: 30}

func MakeLensCurried ¶

func MakeLensCurried[GET ~func(S) A, SET ~func(A) Endomorphism[S], S, A any](get GET, set SET) Lens[S, A]

MakeLensCurried creates a Lens with a curried setter F.

This is similar to MakeLens but accepts a curried setter (A → S → S) instead of an uncurried one (S, A → S). The curried form is more composable in functional pipelines.

The setter must create a (shallow) copy of the data structure. This happens automatically when the data is passed by value. For pointer-based structures, use MakeLensRefCurried.

Type Parameters:

• GET: Getter function type (S → A)
• SET: Curried setter function type (A → S → S)
• S: Source structure type
• A: Focus/field type

Parameters:

• get: Function to extract value A from structure S
• set: Curried function to update value A in structure S

Returns:

• A Lens[S, A] that can get and set values immutably

Example:

nameLens := lens.MakeLensCurried(
    func(p Person) string { return p.Name },
    func(name string) func(Person) Person {
        return func(p Person) Person {
            p.Name = name
            return p
        }
    },
)

func MakeLensCurriedRefWithName ¶

func MakeLensCurriedRefWithName[GET ~func(*S) A, SET ~func(A) Endomorphism[*S], S, A any](get GET, set SET, name string) Lens[*S, A]

MakeLensCurriedRefWithName creates a Lens for pointer-based structures with a curried setter and a custom name.

This is the named variant of MakeLensCurriedRefWithName combined with automatic copy-on-write semantics for pointer receivers. The setter does not need to create a copy manually; the copy is applied by the wrapped curried setter produced by setCopyCurried. The name is used in String, Format, and LogValue for debugging and structured logging.

Type Parameters:

• GET: Getter function type (*S → A)
• SET: Curried setter function type (A → *S → *S)
• S: Source structure type (will be used as *S)
• A: Focus/field type

Parameters:

• get: Function to extract value A from pointer *S
• set: Curried function to update value A in pointer *S (copying handled automatically)
• name: A descriptive name for the lens (used in String() and Format())

Returns:

• A Lens[*S, A] with the specified name

func MakeLensCurriedWithName ¶

func MakeLensCurriedWithName[GET ~func(S) A, SET ~func(A) Endomorphism[S], S, A any](get GET, set SET, name string) Lens[S, A]

MakeLensCurriedWithName creates a Lens with a curried setter and a custom name.

This combines the benefits of MakeLensCurried (curried setter for better composition) with MakeLensWithName (custom name for debugging). The name is useful for debugging complex lens compositions and understanding which lens is being used in error messages or logs.

The setter must create a (shallow) copy of the data structure. This happens automatically when the data is passed by value. For pointer-based structures, use MakeLensRefCurried.

Type Parameters:

• GET: Getter function type (S → A)
• SET: Curried setter function type (A → S → S)
• S: Source structure type
• A: Focus/field type

Parameters:

• get: Function to extract value A from structure S
• set: Curried function to update value A in structure S
• name: A descriptive name for the lens (used in String() and Format())

Returns:

• A Lens[S, A] with the specified name

Example:

type Person struct {
    Name string
    Age  int
}

nameLens := lens.MakeLensCurriedWithName(
    func(p Person) string { return p.Name },
    func(name string) func(Person) Person {
        return func(p Person) Person {
            p.Name = name
            return p
        }
    },
    "Person.Name",
)

fmt.Printf("Using lens: %s\n", nameLens)  // Prints: "Using lens: Person.Name"

func MakeLensRef ¶

func MakeLensRef[GET ~func(*S) A, SET func(*S, A) *S, S, A any](get GET, set SET) Lens[*S, A]

MakeLensRef creates a Lens for pointer-based structures.

Unlike MakeLens, the setter does not need to create a copy manually. This function automatically wraps the setter to create a shallow copy of the pointed-to value before modification, ensuring immutability.

This lens assumes that property A always exists in structure S (i.e., it's not optional).

Type Parameters:

• GET: Getter function type (*S → A)
• SET: Setter function type (*S, A → *S)
• S: Source structure type (will be used as *S)
• A: Focus/field type

Parameters:

• get: Function to extract value A from pointer *S
• set: Function to update value A in pointer *S (copying handled automatically)

Returns:

• A Lens[*S, A] that can get and set values immutably on pointers

Example:

type Person struct {
    Name string
    Age  int
}

nameLens := lens.MakeLensRef(
    func(p *Person) string { return p.Name },
    func(p *Person, name string) *Person {
        p.Name = name  // No manual copy needed
        return p
    },
)

person := &Person{Name: "Alice", Age: 30}
updated := nameLens.Set("Bob")(person)
// person.Name is still "Alice", updated is a new pointer with Name "Bob"

func MakeLensRefCurried ¶

func MakeLensRefCurried[S, A any](get func(*S) A, set func(A) Endomorphism[*S]) Lens[*S, A]

MakeLensRefCurried creates a Lens for pointer-based structures with a curried setter.

This combines the benefits of MakeLensRef (automatic copying) with MakeLensCurried (curried setter for better composition). The setter does not need to create a copy manually; this function automatically wraps it to ensure immutability.

This lens assumes that property A always exists in structure S (i.e., it's not optional).

Type Parameters:

• S: Source structure type (will be used as *S)
• A: Focus/field type

Parameters:

• get: Function to extract value A from pointer *S
• set: Curried function to update value A in pointer *S (copying handled automatically)

Returns:

• A Lens[*S, A] that can get and set values immutably on pointers

Example:

nameLens := lens.MakeLensRefCurried(
    func(p *Person) string { return p.Name },
    func(name string) func(*Person) *Person {
        return func(p *Person) *Person {
            p.Name = name  // No manual copy needed
            return p
        }
    },
)

func MakeLensRefCurriedWithName ¶

func MakeLensRefCurriedWithName[S, A any](get func(*S) A, set func(A) Endomorphism[*S], name string) Lens[*S, A]

MakeLensRefCurriedWithName creates a Lens for pointer-based structures with a curried setter and custom name.

This combines the benefits of MakeLensRefCurried (automatic copying with curried setter) with MakeLensWithName (custom name for debugging). The setter does not need to create a copy manually; this function automatically wraps it to ensure immutability. The curried form is more composable in functional pipelines, and the name is useful for debugging.

This lens assumes that property A always exists in structure S (i.e., it's not optional).

Type Parameters:

• S: Source structure type (will be used as *S)
• A: Focus/field type

Parameters:

• get: Function to extract value A from pointer *S
• set: Curried function to update value A in pointer *S (copying handled automatically)
• name: A descriptive name for the lens (used in String() and Format())

Returns:

• A Lens[*S, A] with the specified name

Example:

type Person struct {
    Name string
    Age  int
}

nameLens := lens.MakeLensRefCurriedWithName(
    func(p *Person) string { return p.Name },
    func(name string) func(*Person) *Person {
        return func(p *Person) *Person {
            p.Name = name  // No manual copy needed
            return p
        }
    },
    "Person.Name",
)

person := &Person{Name: "Alice", Age: 30}
fmt.Printf("Using lens: %s\n", nameLens)  // Prints: "Using lens: Person.Name"
updated := nameLens.Set("Bob")(person)
// person.Name is still "Alice", updated is a new pointer with Name "Bob"

func MakeLensRefWithName ¶

func MakeLensRefWithName[GET ~func(*S) A, SET func(*S, A) *S, S, A any](get GET, set SET, name string) Lens[*S, A]

MakeLensRefWithName creates a Lens for pointer-based structures with a custom name.

This combines MakeLensRef (automatic copying for pointer structures) with MakeLensWithName (custom name for debugging). The setter does not need to create a copy manually; this function automatically wraps it to ensure immutability. The name is useful for debugging complex lens compositions and understanding which lens is being used in error messages or logs.

This lens assumes that property A always exists in structure S (i.e., it's not optional).

Type Parameters:

• GET: Getter function type (*S → A)
• SET: Setter function type (*S, A → *S)
• S: Source structure type (will be used as *S)
• A: Focus/field type

Parameters:

• get: Function to extract value A from pointer *S
• set: Function to update value A in pointer *S (copying handled automatically)
• name: A descriptive name for the lens (used in String() and Format())

Returns:

• A Lens[*S, A] with the specified name

Example:

type Person struct {
    Name string
    Age  int
}

nameLens := lens.MakeLensRefWithName(
    func(p *Person) string { return p.Name },
    func(p *Person, name string) *Person {
        p.Name = name  // No manual copy needed
        return p
    },
    "Person.Name",
)

person := &Person{Name: "Alice", Age: 30}
fmt.Printf("Using lens: %s\n", nameLens)  // Prints: "Using lens: Person.Name"
updated := nameLens.Set("Bob")(person)
// person.Name is still "Alice", updated is a new pointer with Name "Bob"

func MakeLensStrict ¶

func MakeLensStrict[GET ~func(*S) A, SET func(*S, A) *S, S any, A comparable](get GET, set SET) Lens[*S, A]

MakeLensStrict creates a Lens for pointer-based structures with strict equality optimization.

This is a convenience function that combines MakeLensWithEq with strict equality comparison (==). It's suitable for comparable types (primitives, strings, pointers, etc.) and provides the same optimization as MakeLensWithEq: if the new value equals the current value, the original pointer is returned unchanged instead of creating a copy.

The setter does not need to create a copy manually; this function automatically wraps it to ensure immutability when changes are made.

This lens assumes that property A always exists in structure S (i.e., it's not optional).

Type Parameters:

• GET: Getter function type (*S → A)
• SET: Setter function type (*S, A → *S)
• S: Source structure type (will be used as *S)
• A: Focus/field type (must be comparable)

Parameters:

• get: Function to extract value A from pointer *S
• set: Function to update value A in pointer *S (copying handled automatically)

Returns:

• A Lens[*S, A] that can get and set values immutably on pointers with strict equality optimization

Example:

type Person struct {
    Name string
    Age  int
}

// Using MakeLensStrict for a string field (comparable type)
nameLens := lens.MakeLensStrict(
    func(p *Person) string { return p.Name },
    func(p *Person, name string) *Person {
        p.Name = name  // No manual copy needed
        return p
    },
)

person := &Person{Name: "Alice", Age: 30}

// Setting the same value returns the original pointer (no copy)
same := nameLens.Set("Alice")(person)
// same == person (same pointer)

// Setting a different value creates a new copy
updated := nameLens.Set("Bob")(person)
// person.Name is still "Alice", updated is a new pointer with Name "Bob"

func MakeLensStrictWithName ¶

func MakeLensStrictWithName[GET ~func(*S) A, SET func(*S, A) *S, S any, A comparable](get GET, set SET, name string) Lens[*S, A]

MakeLensStrictWithName creates a Lens for pointer-based structures with strict equality optimization and a custom name.

This combines MakeLensStrict (strict equality optimization using ==) with MakeLensWithName (custom name for debugging). It's a convenience function suitable for comparable types (primitives, strings, pointers, etc.). If the new value equals the current value, the original pointer is returned unchanged instead of creating a copy. The name is useful for debugging.

The setter does not need to create a copy manually; this function automatically wraps it to ensure immutability when changes are made.

This lens assumes that property A always exists in structure S (i.e., it's not optional).

Type Parameters:

• GET: Getter function type (*S → A)
• SET: Setter function type (*S, A → *S)
• S: Source structure type (will be used as *S)
• A: Focus/field type (must be comparable)

Parameters:

• get: Function to extract value A from pointer *S
• set: Function to update value A in pointer *S (copying handled automatically)
• name: A descriptive name for the lens (used in String() and Format())

Returns:

• A Lens[*S, A] with strict equality optimization and the specified name

Example:

type Person struct {
    Name string
    Age  int
}

// Using MakeLensStrictWithName for a string field (comparable type)
nameLens := lens.MakeLensStrictWithName(
    func(p *Person) string { return p.Name },
    func(p *Person, name string) *Person {
        p.Name = name  // No manual copy needed
        return p
    },
    "Person.Name",
)

person := &Person{Name: "Alice", Age: 30}
fmt.Printf("Using lens: %s\n", nameLens)  // Prints: "Using lens: Person.Name"

// Setting the same value returns the original pointer (no copy)
same := nameLens.Set("Alice")(person)  // same == person

// Setting a different value creates a new copy
updated := nameLens.Set("Bob")(person)  // person.Name still "Alice"

func MakeLensWithEq ¶

func MakeLensWithEq[GET ~func(*S) A, SET func(*S, A) *S, S, A any](pred EQ.Eq[A], get GET, set SET) Lens[*S, A]

MakeLensWithEq creates a Lens for pointer-based structures with equality optimization.

This is similar to MakeLensRef but includes an optimization: if the new value equals the current value (according to the provided Eq predicate), the original pointer is returned unchanged instead of creating a copy. This can improve performance and reduce allocations when setting values that don't actually change the structure.

The setter does not need to create a copy manually; this function automatically wraps it to ensure immutability when changes are made.

This lens assumes that property A always exists in structure S (i.e., it's not optional).

Type Parameters:

• GET: Getter function type (*S → A)
• SET: Setter function type (*S, A → *S)
• S: Source structure type (will be used as *S)
• A: Focus/field type

Parameters:

• pred: Equality predicate to compare values of type A
• get: Function to extract value A from pointer *S
• set: Function to update value A in pointer *S (copying handled automatically)

Returns:

• A Lens[*S, A] that can get and set values immutably on pointers with equality optimization

Example:

type Person struct {
    Name string
    Age  int
}

nameLens := lens.MakeLensWithEq(
    eq.FromStrictEquals[string](),
    func(p *Person) string { return p.Name },
    func(p *Person, name string) *Person {
        p.Name = name  // No manual copy needed
        return p
    },
)

person := &Person{Name: "Alice", Age: 30}

// Setting the same value returns the original pointer (no copy)
same := nameLens.Set("Alice")(person)
// same == person (same pointer)

// Setting a different value creates a new copy
updated := nameLens.Set("Bob")(person)
// person.Name is still "Alice", updated is a new pointer with Name "Bob"

func MakeLensWithEqWithName ¶

func MakeLensWithEqWithName[GET ~func(*S) A, SET func(*S, A) *S, S, A any](pred EQ.Eq[A], get GET, set SET, name string) Lens[*S, A]

MakeLensWithEqWithName creates a Lens for pointer-based structures with equality optimization and a custom name.

This combines MakeLensWithEq (equality optimization) with MakeLensWithName (custom name for debugging). If the new value equals the current value (according to the provided Eq predicate), the original pointer is returned unchanged instead of creating a copy. The name is useful for debugging complex lens compositions.

The setter does not need to create a copy manually; this function automatically wraps it to ensure immutability when changes are made.

This lens assumes that property A always exists in structure S (i.e., it's not optional).

Type Parameters:

• GET: Getter function type (*S → A)
• SET: Setter function type (*S, A → *S)
• S: Source structure type (will be used as *S)
• A: Focus/field type

Parameters:

• pred: Equality predicate to compare values of type A
• get: Function to extract value A from pointer *S
• set: Function to update value A in pointer *S (copying handled automatically)
• name: A descriptive name for the lens (used in String() and Format())

Returns:

• A Lens[*S, A] with equality optimization and the specified name

Example:

type Person struct {
    Name string
    Age  int
}

nameLens := lens.MakeLensWithEqWithName(
    eq.FromStrictEquals[string](),
    func(p *Person) string { return p.Name },
    func(p *Person, name string) *Person {
        p.Name = name  // No manual copy needed
        return p
    },
    "Person.Name",
)

person := &Person{Name: "Alice", Age: 30}
fmt.Printf("Using lens: %s\n", nameLens)  // Prints: "Using lens: Person.Name"

// Setting the same value returns the original pointer (no copy)
same := nameLens.Set("Alice")(person)  // same == person

// Setting a different value creates a new copy
updated := nameLens.Set("Bob")(person)  // person.Name still "Alice"

func MakeLensWithName ¶

func MakeLensWithName[GET ~func(S) A, SET ~func(S, A) S, S, A any](get GET, set SET, name string) Lens[S, A]

MakeLensWithName creates a Lens with a custom name for debugging and logging.

This is identical to MakeLens but allows you to specify a name that will be used when the lens is printed or formatted. The name is useful for debugging complex lens compositions and understanding which lens is being used in error messages or logs.

The setter must create a (shallow) copy of the data structure. This happens automatically when the data is passed by value. For pointer-based structures, use MakeLensRef instead.

Type Parameters:

• GET: Getter function type (S → A)
• SET: Setter function type (S, A → S)
• S: Source structure type
• A: Focus/field type

Parameters:

• get: Function to extract value A from structure S
• set: Function to update value A in structure S, returning a new S
• name: A descriptive name for the lens (used in String() and Format())

Returns:

• A Lens[S, A] with the specified name

Example:

type Person struct {
    Name string
    Age  int
}

nameLens := lens.MakeLensWithName(
    func(p Person) string { return p.Name },
    func(p Person, name string) Person {
        p.Name = name
        return p
    },
    "Person.Name",
)

fmt.Printf("Using lens: %s\n", nameLens)  // Prints: "Using lens: Person.Name"

func LensComposeIso ¶

func LensComposeIso[S, A, B any](ab Iso[A, B]) LensOperator[S, A, B]

LensComposeIso converts a Lens to a property of `A` into a lens to a property of type `B` the transformation is done via an ISO

func LensComposeLens ¶

func LensComposeLens[S, A, B any](ab Lens[A, B]) LensOperator[S, A, B]

LensComposeLens combines two lenses to focus on a deeply nested field.

Given a lens from S to A and a lens from A to B, LensComposeLens creates a lens from S to B. This allows you to navigate through nested structures in a composable way.

The composition follows the mathematical property: (sa ∘ ab).Get = ab.Get ∘ sa.Get

Type Parameters:

• S: Outer structure type
• A: Intermediate structure type
• B: Inner focus type

Parameters:

• ab: Lens from A to B (inner lens)

Returns:

• A function that takes a Lens[S, A] and returns a Lens[S, B]

Example:

type Address struct {
    Street string
    City   string
}

type Person struct {
    Name    string
    Address Address
}

addressLens := lens.MakeLens(
    func(p Person) Address { return p.Address },
    func(p Person, a Address) Person { p.Address = a; return p },
)

streetLens := lens.MakeLens(
    func(a Address) string { return a.Street },
    func(a Address, s string) Address { a.Street = s; return a },
)

// LensComposeLens to access street directly from person
personStreetLens := F.Pipe1(addressLens, lens.LensComposeLens[Person](streetLens))

person := Person{Name: "Alice", Address: Address{Street: "Main St"}}
street := personStreetLens.Get(person)  // "Main St"
updated := personStreetLens.Set("Oak Ave")(person)

func LensIMap ¶

func LensIMap[S any, AB ~func(A) B, BA ~func(B) A, A, B any](ab AB, ba BA) LensOperator[S, A, B]

LensIMap transforms the focus type of a lens using an isomorphism.

An isomorphism is a pair of functions (A → B, B → A) that are inverses of each other. LensIMap allows you to work with a lens in a different but equivalent type. This is useful for unit conversions, encoding/decoding, or any bidirectional transformation.

Type Parameters:

• E: Structure type
• AB: Forward transformation function type (A → B)
• BA: Backward transformation function type (B → A)
• A: Original focus type
• B: Transformed focus type

Parameters:

• ab: Forward transformation (A → B)
• ba: Backward transformation (B → A)

Returns:

• A function that takes a Lens[E, A] and returns a Lens[E, B]

Example:

type Celsius float64
type Fahrenheit float64

celsiusToFahrenheit := func(c Celsius) Fahrenheit {
    return Fahrenheit(c*9/5 + 32)
}

fahrenheitToCelsius := func(f Fahrenheit) Celsius {
    return Celsius((f - 32) * 5 / 9)
}

type Weather struct {
    Temperature Celsius
}

tempCelsiusLens := lens.MakeLens(
    func(w Weather) Celsius { return w.Temperature },
    func(w Weather, t Celsius) Weather { w.Temperature = t; return w },
)

// Create a lens that works with Fahrenheit
tempFahrenheitLens := F.Pipe1(
    tempCelsiusLens,
    lens.LensIMap[Weather](celsiusToFahrenheit, fahrenheitToCelsius),
)

weather := Weather{Temperature: 20} // 20°C
tempF := tempFahrenheitLens.Get(weather)  // 68°F
updated := tempFahrenheitLens.Set(86)(weather)  // Set to 86°F (30°C)

func OptionFlatten ¶ added in v2.3.120

func OptionFlatten[A any](mma Option[Option[A]]) Option[A]

OptionFlatten removes one level of nesting from a nested Option.

Example:

nested := OptionSome(OptionSome(42))
result := OptionFlatten(nested) // OptionSome(42)
nested := OptionSome(OptionNone[int]())
result := OptionFlatten(nested) // None

func OptionFromNillable2 ¶ added in v2.3.120

func OptionFromNillable2[A any](a *A) Option[A]

OptionFromNillable2 converts a pointer to an Option of the pointed-to value. Returns OptionSome(value) when the pointer is non-nil (dereferencing it), None otherwise. This is the preferred alternative to FromNillable because the resulting Option[A] composes naturally with Map, Chain, and the rest of the Option API without having to deal with an intermediate pointer inside the Option.

Type Parameters:

• A: the type that the pointer points to

Parameters:

• a: a pointer to a value of type A; may be nil

Returns:

• OptionSome(*a) when a is non-nil
• None when a is nil

See Also:

• ToNillable2: the inverse — converts Option[A] back to *A
• FromNillable: the older variant that wraps the pointer itself as Option[*A]

func OptionInstanceOf ¶ added in v2.3.120

func OptionInstanceOf[T any](src any) Option[T]

OptionInstanceOf attempts to convert a value of type any to a specific type T using type assertion. Returns Some(value) if the type assertion succeeds, None if it fails.

Example:

var x any = 42
result := OptionInstanceOf[int](x) // Some(42)

var y any = "hello"
result := OptionInstanceOf[int](y) // None (wrong type)

func OptionMonadAlt ¶ added in v2.3.120

func OptionMonadAlt[A any](fa Option[A], that func() Option[A]) Option[A]

MonadAlt returns the first Option if it's Some, otherwise returns the alternative. This is the monadic form of the Alt operation.

Example:

result := MonadAlt(OptionSome(5), func() Option[int] { return OptionSome(10) }) // OptionSome(5)
result := MonadAlt(OptionNone[int](), func() Option[int] { return OptionSome(10) }) // OptionSome(10)

func OptionMonadAp ¶ added in v2.3.120

func OptionMonadAp[B, A any](fab Option[func(A) B], fa Option[A]) Option[B]

OptionMonadAp applies a function wrapped in an Option to a value wrapped in an Option. If either the function or the value is None, returns None. This is the monadic form of the applicative functor.

Example:

fab := OptionSome(N.Mul(2))
fa := OptionSome(5)
result := OptionMonadAp(fab, fa) // OptionSome(10)

func OptionMonadChain ¶ added in v2.3.120

func OptionMonadChain[A, B any](fa Option[A], f OptionKleisli[A, B]) Option[B]

OptionMonadChain applies a function that returns an Option to the value inside an Option. This is the monadic bind operation. If the input is None, returns None.

Example:

fa := OptionSome(5)
result := OptionMonadChain(fa, F.Flow2(Predicate(N.MoreThan(0)), Map(N.Mul(2)))) // OptionSome(10)

func OptionMonadChainFirst ¶ added in v2.3.120

func OptionMonadChainFirst[A, B any](ma Option[A], f OptionKleisli[A, B]) Option[A]

OptionMonadChainFirst applies a function that returns an Option but keeps the original value. If either operation results in None, returns None.

Example:

result := OptionMonadChainFirst(OptionSome(5), func(x int) Option[string] {
    return OptionSome(fmt.Sprintf("%d", x))
}) // OptionSome(5) - original value is kept

func OptionMonadChainTo ¶ added in v2.3.120

func OptionMonadChainTo[A, B any](ma Option[A], mb Option[B]) Option[B]

OptionMonadChainTo ignores the first Option and returns the second Option. Useful for sequencing operations where the first result is not needed.

Example:

result := OptionMonadChainTo(OptionSome(5), OptionSome("hello")) // OptionSome("hello")

func OptionMonadFlap ¶ added in v2.3.120

func OptionMonadFlap[B, A any](fab Option[func(A) B], a A) Option[B]

OptionMonadFlap applies a value to a function wrapped in an Option. This is the monadic form of Flap.

Example:

fab := OptionSome(N.Mul(2))
result := OptionMonadFlap(fab, 5) // OptionSome(10)

func OptionMonadMap ¶ added in v2.3.120

func OptionMonadMap[A, B any](fa Option[A], f func(A) B) Option[B]

OptionMonadMap applies a function to the value inside an Option. If the Option is None, returns None. This is the monadic form of Map.

Example:

fa := OptionSome(5)
result := OptionMonadMap(fa, N.Mul(2)) // OptionSome(10)

func OptionMonadMapTo ¶ added in v2.3.120

func OptionMonadMapTo[A, B any](fa Option[A], b B) Option[B]

OptionMonadMapTo replaces the value inside an Option with a constant value. If the Option is None, returns None. This is the monadic form of MapTo.

Example:

fa := OptionSome(5)
result := OptionMonadMapTo(fa, "hello") // OptionSome("hello")

func OptionMonadSequence2 ¶ added in v2.3.120

func OptionMonadSequence2[T1, T2, R any](o1 Option[T1], o2 Option[T2], f func(T1, T2) Option[R]) Option[R]

OptionMonadSequence2 sequences two Options and applies a function to their values. Returns None if either Option is None.

Example:

result := OptionMonadSequence2(OptionSome(2), OptionSome(3), func(a, b int) Option[int] {
    return OptionSome(a + b)
}) // OptionSome(5)

func OptionNone ¶ added in v2.3.120

func OptionNone[T any]() Option[T]

OptionNone creates an Option that contains no value.

Example:

opt := OptionNone[int]() // Empty Option of type int
opt := OptionNone[string]() // Empty Option of type string

func OptionOf ¶ added in v2.3.120

func OptionOf[T any](value T) Option[T]

OptionOf creates an Option that contains a value. This is an alias for OptionSome and is used in monadic contexts.

Example:

opt := OptionOf(42) // Option containing 42

func OptionSequenceArray ¶ added in v2.3.120

func OptionSequenceArray[A any](ma []Option[A]) Option[[]A]

OptionSequenceArray converts an array of Options into an Option of an array. Returns Some containing all values if all Options are Some, None if any is None.

Example:

result := OptionSequenceArray(A.From(OptionSome(1), OptionSome(2), OptionSome(3))) // OptionSome([1, 2, 3])
result := OptionSequenceArray(A.From(OptionSome(1), OptionNone[int](), OptionSome(3))) // None

func OptionSequenceArrayG ¶ added in v2.3.120

func OptionSequenceArrayG[GA ~[]A, GOA ~[]Option[A], A any](ma GOA) Option[GA]

OptionSequenceArrayG converts an array of Options into an Option of an array. Returns Some containing all values if all Options are Some, None if any is None. This is the generic version that works with custom slice types.

Example:

type MySlice []int
result := OptionSequenceArrayG[MySlice](A.From(OptionSome(1), OptionSome(2))) // OptionSome(MySlice{1, 2})
result := OptionSequenceArrayG[MySlice](A.From(OptionSome(1), OptionNone[int]())) // None

func OptionSome ¶ added in v2.3.120

func OptionSome[T any](value T) Option[T]

OptionSome creates an Option that contains a value.

Example:

opt := OptionSome(42) // Option containing 42
opt := OptionSome("hello") // Option containing "hello"

func OptionToAny ¶ added in v2.3.120

func OptionToAny[T any](src T) Option[any]

OptionToAny converts a value of any type to Option[any]. This always succeeds and returns Some containing the value as any.

Example:

result := OptionToAny(42) // Some(any(42))
result := OptionToAny("hello") // Some(any("hello"))

func OptionTryCatch ¶ added in v2.3.120

func OptionTryCatch[A any](f func() (A, error)) Option[A]

OptionTryCatch executes a function that may return an error and converts the result to an Option. Returns OptionSome(value) if no error occurred, None if an error occurred.

Example:

result := OptionTryCatch(func() (int, error) {
    return strconv.Atoi("42")
}) // OptionSome(42)

func OptionZero ¶ added in v2.3.120

func OptionZero[A any]() Option[A]

OptionZero returns the zero value of an Option, which is None. This function is useful as an identity element in monoid operations or for creating an empty Option.

The zero value for Option[A] is always None, representing the absence of a value. This is consistent with the Option monad's semantics where None represents "no value" and Some represents "a value".

Important: OptionZero() returns the same value as the default initialization of Option[A]. When you declare `var o Option[A]` without initialization, it has the same value as OptionZero[A]().

Note: Unlike other types where zero might be a default value, Option's zero is explicitly the absence of any value (None), not Some with a zero value.

Example:

// OptionZero Option of any type is always None
o1 := option.OptionZero[int]()     // None
o2 := option.OptionZero[string]()  // None
o3 := option.OptionZero[*int]()    // None

// OptionZero equals default initialization
var defaultInit Option[int]
zero := option.OptionZero[int]()
assert.Equal(t, defaultInit, zero) // true

// Verify it's None
o := option.OptionZero[int]()
assert.True(t, option.IsNone(o))   // true
assert.False(t, option.IsOptionSome(o))  // false

// Different from Some with zero value
someZero := option.OptionSome(0)         // OptionSome(0)
zero := option.OptionZero[int]()         // None
assert.NotEqual(t, someZero, zero) // they are different

func OptionFromNonZero ¶ added in v2.3.120

func OptionFromNonZero[A comparable]() OptionKleisli[A, A]

func OptionFromPredicate ¶ added in v2.3.120

func OptionFromPredicate[A any](pred Predicate[A]) OptionKleisli[A, A]

OptionFromPredicate returns a function that creates an Option based on a predicate. The returned function will wrap a value in Some if the predicate is satisfied, otherwise None.

Example:

isPositive := OptionFromPredicate(N.MoreThan(0))
result := isPositive(5)  // OptionSome(5)
result := isPositive(-1) // None

func OptionFromValidation ¶ added in v2.3.120

func OptionFromValidation[A, B any](f func(A) (B, bool)) OptionKleisli[A, B]

OptionFromValidation converts a validation function (returning value and bool) to an Option-returning function. This is an alias for Optionize1.

Example:

parseNum := OptionFromValidation(func(s string) (int, bool) {
    n, err := strconv.Atoi(s)
    return n, err == nil
})
result := parseNum("42") // OptionSome(42)

func OptionFromZero ¶ added in v2.3.120

func OptionFromZero[A comparable]() OptionKleisli[A, A]

func OptionOptionize1 ¶ added in v2.3.120

func OptionOptionize1[F ~func(T0) (R, bool), T0, R any](f F) OptionKleisli[T0, R]

OptionOptionize1 converts a function with 1 parameters returning a tuple of a return value R and a boolean into a function with 1 parameters returning an Option[R]

func OptionTraverseArray ¶ added in v2.3.120

func OptionTraverseArray[A, B any](f OptionKleisli[A, B]) OptionKleisli[[]A, []B]

OptionTraverseArray transforms an array by applying a function that returns an Option to each element. Returns Some containing the array of results if all operations succeed, None if any fails.

Example:

validate := F.Flow2(Predicate(N.MoreThan(0)), Map(N.Mul(2)))
result := OptionTraverseArray(validate)([]int{1, 2, 3}) // OptionSome([2, 4, 6])
result := OptionTraverseArray(validate)([]int{1, -1, 3}) // None

func OptionTraverseArrayG ¶ added in v2.3.120

func OptionTraverseArrayG[GA ~[]A, GB ~[]B, A, B any](f OptionKleisli[A, B]) OptionKleisli[GA, GB]

OptionTraverseArrayG transforms an array by applying a function that returns an Option to each element. Returns Some containing the array of results if all operations succeed, None if any fails. This is the generic version that works with custom slice types.

Example:

parse := func(s string) Option[int] {
    n, err := strconv.Atoi(s)
    if err != nil { return OptionNone[int]() }
    return OptionSome(n)
}
result := OptionTraverseArrayG[[]string, []int](parse)([]string{"1", "2", "3"}) // OptionSome([1, 2, 3])
result := OptionTraverseArrayG[[]string, []int](parse)([]string{"1", "x", "3"}) // None

func OptionTraverseArrayWithIndex ¶ added in v2.3.120

func OptionTraverseArrayWithIndex[A, B any](f func(int, A) Option[B]) OptionKleisli[[]A, []B]

OptionTraverseArrayWithIndex transforms an array by applying an indexed function that returns an Option. The function receives both the index and the element.

Example:

f := func(i int, x int) Option[int] {
    if x > i { return OptionSome(x) }
    return OptionNone[int]()
}
result := OptionTraverseArrayWithIndex(f)([]int{1, 2, 3}) // OptionSome([1, 2, 3])

func OptionTraverseArrayWithIndexG ¶ added in v2.3.120

func OptionTraverseArrayWithIndexG[GA ~[]A, GB ~[]B, A, B any](f func(int, A) Option[B]) OptionKleisli[GA, GB]

OptionTraverseArrayWithIndexG transforms an array by applying an indexed function that returns an Option. The function receives both the index and the element. This is the generic version that works with custom slice types.

Example:

f := func(i int, s string) Option[string] {
    return OptionSome(fmt.Sprintf("%d:%s", i, s))
}
result := OptionTraverseArrayWithIndexG[[]string, []string](f)([]string{"a", "b"}) // OptionSome(["0:a", "1:b"])

func OptionAlt ¶ added in v2.3.120

func OptionAlt[A any](that func() Option[A]) OptionOperator[A, A]

OptionAlt returns a function that provides an alternative Option if the input is None.

Example:

withDefault := OptionAlt(func() Option[int] { return OptionSome(0) })
result := withDefault(OptionSome(5)) // OptionSome(5)
result := withDefault(OptionNone[int]()) // OptionSome(0)

func OptionAp ¶ added in v2.3.120

func OptionAp[B, A any](fa Option[A]) OptionOperator[func(A) B, B]

OptionAp is the curried applicative functor for Option. Returns a function that applies an Option-wrapped function to the given Option value.

Example:

fa := OptionSome(5)
applyTo5 := OptionAp[int](fa)
fab := OptionSome(N.Mul(2))
result := applyTo5(fab) // OptionSome(10)

func OptionChain ¶ added in v2.3.120

func OptionChain[A, B any](f OptionKleisli[A, B]) OptionOperator[A, B]

OptionChain returns a function that applies an Option-returning function to an Option value. This is the curried form of the monadic bind operation.

Example:

validate := OptionChain(F.Flow2(Predicate(N.MoreThan(0)), Map(N.Mul(2))))
result := validate(OptionSome(5)) // OptionSome(10)

func OptionChainFirst ¶ added in v2.3.120

func OptionChainFirst[A, B any](f OptionKleisli[A, B]) OptionOperator[A, A]

OptionChainFirst returns a function that applies an Option-returning function but keeps the original value.

Example:

logAndKeep := OptionChainFirst(func(x int) Option[string] {
    fmt.Println(x)
    return OptionSome("logged")
})
result := logAndKeep(OptionSome(5)) // OptionSome(5)

func OptionChainOptionNone ¶ added in v2.3.120

func OptionChainOptionNone[A any](onNone func() Option[A]) OptionOperator[A, A]

ChainNone is the curried version that sequences a computation on the None (empty) value. Returns a function that applies the provided function when the Option is None, or returns None when the Option is Some.

Note: ChainNone is identical to Alt - both provide the same functionality for providing alternative values when an Option is None.

The naming convention follows the pattern established by ChainLeft in the Either type, where operations on the "error" or "empty" case use the Left/None suffix to distinguish them from operations on the "success" or "present" case (Chain operates on Some values, while ChainNone operates on None values).

This is useful for creating reusable default value providers or transformers that can be composed with other Option operations using pipes or function composition.

Example:

// Create a reusable default provider
provideDefault := option.ChainNone(func() option.Option[int] {
    return option.OptionSome(42)
})

// Use in a pipeline
result := F.Pipe1(
    option.OptionNone[int](),
    provideDefault,
) // OptionSome(42)

// Some values pass through unchanged
result := F.Pipe1(
    option.OptionSome(10),
    provideDefault,
) // OptionSome(10)

func OptionChainTo ¶ added in v2.3.120

func OptionChainTo[A, B any](mb Option[B]) OptionOperator[A, B]

OptionChainTo returns a function that ignores its input Option and returns a fixed Option.

Example:

replaceWith := OptionChainTo(OptionSome("hello"))
result := replaceWith(OptionSome(42)) // OptionSome("hello")

func OptionFilter ¶ added in v2.3.120

func OptionFilter[A any](pred Predicate[A]) OptionOperator[A, A]

OptionFilter keeps the Option if it's Some and the predicate is satisfied, otherwise returns None.

Example:

isPositive := OptionFilter(N.MoreThan(0))
result := isPositive(OptionSome(5)) // OptionSome(5)
result := isPositive(OptionSome(-1)) // None
result := isPositive(OptionNone[int]()) // None

func OptionFlap ¶ added in v2.3.120

func OptionFlap[B, A any](a A) OptionOperator[func(A) B, B]

OptionFlap returns a function that applies a value to an Option-wrapped function.

Example:

applyFive := OptionFlap[int](5)
fab := OptionSome(N.Mul(2))
result := applyFive(fab) // OptionSome(10)

func OptionMap ¶ added in v2.3.120

func OptionMap[A, B any](f func(a A) B) OptionOperator[A, B]

OptionMap returns a function that applies a transformation to the value inside an Option. If the Option is None, returns None.

Example:

double := OptionMap(N.Mul(2))
result := double(OptionSome(5)) // OptionSome(10)
result := double(OptionNone[int]()) // None

func OptionMapTo ¶ added in v2.3.120

func OptionMapTo[A, B any](b B) OptionOperator[A, B]

OptionMapTo returns a function that replaces the value inside an Option with a constant.

Example:

replaceWith42 := OptionMapTo[string, int](42)
result := replaceWith42(OptionSome("hello")) // OptionSome(42)

func OptionTraversableArray ¶ added in v2.3.120

func OptionTraversableArray[A, B any]() OptionTraversable[A, B, []A, []B]

OptionTraversableArray returns a Traversable instance for arrays. A Traversable represents a data structure that can be traversed from left to right, applying an effectful function to each element and collecting the results.

This function provides a way to obtain the traversal operation for arrays as a first-class value, which is useful when you need to pass the traversal operation as a parameter or compose it with other operations.

Type Parameters:

• A: The input element type
• B: The output element type

Returns:

• Traversable[A, B, []A, []B]: A function that takes a Kleisli arrow and returns another Kleisli arrow that operates on arrays

The returned Traversable has the signature:

func(OptionKleisli[A, B]) OptionKleisli[[]A, []B]

which is equivalent to:

func(func(A) Option[B]) func([]A) Option[[]B]

Example:

// Get the traversable instance
traversable := OptionTraversableArray[string, int]()

// Use it with a parsing function
parse := func(s string) Option[int] {
    n, err := strconv.Atoi(s)
    if err != nil { return OptionNone[int]() }
    return OptionSome(n)
}
result := traversable(parse)([]string{"1", "2", "3"}) // OptionSome([1, 2, 3])

See Also:

• TraverseArray: Direct traversal without obtaining the Traversable instance
• TraverseArrayG: Generic version supporting custom slice types

func MakeOptional ¶

func MakeOptional[S, A any](get OptionKleisli[S, A], set func(S, A) S) Optional[S, A]

MakeOptional creates an Optional based on a getter and a setter function. Make sure that the setter creates a (shallow) copy of the data. This happens automatically if the data is passed by value. For pointers consider to use `MakeOptionalRef` and for other kinds of data structures that are copied by reference make sure the setter creates the copy.

func MakeOptionalCurried ¶

func MakeOptionalCurried[S, A any](get OptionKleisli[S, A], set func(A) func(S) S) Optional[S, A]

func MakeOptionalCurriedWithName ¶

func MakeOptionalCurriedWithName[S, A any](get OptionKleisli[S, A], set func(A) func(S) S, name string) Optional[S, A]

func MakeOptionalRef ¶

func MakeOptionalRef[S, A any](get OptionKleisli[*S, A], set func(*S, A) *S) Optional[*S, A]

MakeOptionalRef creates an Optional based on a getter and a setter function. The setter passed in does not have to create a shallow copy, the implementation wraps the setter into one that copies the pointer before modifying it

func MakeOptionalRefCurriedWithName ¶

func MakeOptionalRefCurriedWithName[S, A any](get OptionKleisli[*S, A], set func(A) func(*S) *S, name string) Optional[*S, A]

func MakeOptionalRefWithName ¶

func MakeOptionalRefWithName[S, A any](get OptionKleisli[*S, A], set func(*S, A) *S, name string) Optional[*S, A]

func MakeOptionalWithName ¶

func MakeOptionalWithName[S, A any](get OptionKleisli[S, A], set func(S, A) S, name string) Optional[S, A]

func OptionalId ¶

func OptionalId[S any]() Optional[S, S]

OptionalId returns am optional implementing the identity operation

func OptionalIdRef ¶

func OptionalIdRef[S any]() Optional[*S, *S]

Id returns am optional implementing the identity operation

func OptionalComposeOptional ¶

func OptionalComposeOptional[S, A, B any](ab Optional[A, B]) OptionalOperator[S, A, B]

OptionalComposeOptional combines two Optional and allows to narrow down the focus to a sub-Optional

func OptionalComposeOptionalRef ¶

func OptionalComposeOptionalRef[S, A, B any](ab Optional[A, B]) OptionalOperator[*S, A, B]

OptionalComposeOptionalRef combines two Optional and allows to narrow down the focus to a sub-Optional

func OptionalIChain ¶

func OptionalIChain[S, A, B any](ab OptionKleisli[A, B], ba OptionKleisli[B, A]) OptionalOperator[S, A, B]

OptionalIChain implements a bidirectional mapping of the transform if the transform can produce optionals (e.g. in case of type mappings)

func OptionalIChainAny ¶

func OptionalIChainAny[S, A any]() OptionalOperator[S, any, A]

OptionalIChainAny implements a bidirectional mapping to and from any

func OptionalIMap ¶

func OptionalIMap[S, A, B any](ab func(A) B, ba func(B) A) OptionalOperator[S, A, B]

OptionalIMap implements a bidirectional mapping of the transform

func OptionExists ¶ added in v2.3.120

func OptionExists[T any](p Predicate[T]) Predicate[Option[T]]

OptionExists creates a predicate that tests whether an Option value is Some and its value satisfies the given predicate. It returns a function that takes an Option[T] and returns true only if the Option is Some and the predicate p returns true for the contained value.

This function is useful for checking if an Option contains a value that meets certain criteria, commonly used in filtering operations, validation chains, or conditional logic where you need to verify both the presence of a value and a property of that value.

The behavior is as follows:

• If the input is None, returns false (regardless of the predicate)
• If the input is Some and p returns true for the contained value, returns true
• If the input is Some and p returns false for the contained value, returns false

Type Parameters:

• T: The type of the value contained in the Option

Parameters:

• p: A predicate function that tests values of type T

Returns:

A Predicate function that takes an Option[T] and returns true if it's Some and satisfies p

Example:

import (
    O "github.com/IBM/fp-go/v2/option"
    N "github.com/IBM/fp-go/v2/number"
)

// Check if Option contains a positive number
isPositive := N.MoreThan(0)
hasPositive := O.OptionExists(isPositive)

result1 := hasPositive(O.Some(5))
// result1 = true (Some with positive value)

result2 := hasPositive(O.Some(-3))
// result2 = false (Some with non-positive value)

result3 := hasPositive(O.None[int]())
// result3 = false (None value)

// Use in filtering
values := []O.Option[int]{
    O.Some(5),
    O.None[int](),
    O.Some(-3),
    O.Some(10),
}
hasPositiveValue := func(opt O.Option[int]) bool {
    return hasPositive(opt)
}
// Filter to keep only Options with positive Some values
// filtered would contain: [Some(5), Some(10)]

See Also:

• Filter: Converts Some values that fail a predicate to None
• IsSome: Tests if Option is Some without checking the value

func OptionForAll ¶ added in v2.3.120

func OptionForAll[T any](p Predicate[T]) Predicate[Option[T]]

OptionForAll creates a predicate that tests whether an Option value is None or its Some value satisfies the given predicate. It returns a function that takes an Option[T] and returns true if the Option is None (regardless of content) or if it's Some and the predicate p returns true for the contained value.

This function implements universal quantification over the Option type. In logical terms, it states: "for all values in the Option, the predicate holds" - which is vacuously true for None values (empty case) and requires the predicate to hold for Some values (non-empty case).

The behavior is as follows:

• If the input is None, returns true (vacuous truth - predicate holds for empty case)
• If the input is Some and p returns true for the contained value, returns true
• If the input is Some and p returns false for the contained value, returns false

Relationship to Haskell and Category Theory:

In Haskell, this corresponds to the all function for the Maybe type when viewed as a Foldable:

all :: Foldable t => (a -> Bool) -> t a -> Bool
all p (Just x)  = p x
all p Nothing   = True

From a category theory perspective, Option[T] is a sum type representing optional values. OptionForAll implements a natural transformation from predicates on T to predicates on Option[T], preserving the logical structure where:

• The None case represents the "empty" or "absent" case
• The Some case represents the "present" case that must satisfy the predicate

This is dual to Exists, which implements existential quantification:

• OptionForAll: "all elements satisfy p" (true for empty, requires p for non-empty)
• Exists: "some element satisfies p" (false for empty, requires p for non-empty)

The relationship follows De Morgan's laws:

• OptionForAll(p) ≡ not(Exists(not(p)))
• Exists(p) ≡ not(OptionForAll(not(p)))

Type Parameters:

• T: The type of the value contained in the Option

Parameters:

• p: A predicate function that tests values of type T

Returns:

A Predicate function that takes an Option[T] and returns true if it's None or Some with p satisfied

Example:

import (
    O "github.com/IBM/fp-go/v2/option"
    N "github.com/IBM/fp-go/v2/number"
)

// Check if Option is None or contains a positive number
isPositive := N.MoreThan(0)
allPositive := O.OptionForAll(isPositive)

result1 := allPositive(O.Some(5))
// result1 = true (Some with positive value satisfies predicate)

result2 := allPositive(O.Some(-3))
// result2 = false (Some with non-positive value fails predicate)

result3 := allPositive(O.None[int]())
// result3 = true (None is vacuously true - no value to check)

// Use in validation: ensure all present values meet criteria
values := []O.Option[int]{
    O.Some(5),
    O.None[int](),        // Ignored (vacuously true)
    O.Some(10),
    O.Some(-3),           // Fails validation
}
allValid := true
for _, v := range values {
    if !allPositive(v) {
        allValid = false
        break
    }
}
// allValid would be false because Some(-3) fails the predicate

// Contrast with Exists:
hasPositive := O.Exists(isPositive)
// hasPositive checks if there EXISTS a Some value satisfying p
// allPositive checks if ALL Some values satisfy p (None is ignored)

See Also:

• Exists: Tests if Option is Some and satisfies a predicate (existential quantification)
• Filter: Converts Some values that fail a predicate to None
• IsSome: Tests if Option is Some without checking the value

func MakePrism ¶

func MakePrism[S, A any](get OptionKleisli[S, A], rev func(A) S) Prism[S, A]

MakePrism constructs a Prism from GetOption and ReverseGet functions.

Parameters:

• get: Function to extract A from S (returns Option[A])
• rev: Function to construct S from A

Returns:

• A Prism[S, A] that uses the provided functions

Example:

prism := MakePrism(
    func(opt Option[int]) Option[int] { return opt },
    func(n int) Option[int] { return Some(n) },
)

func MakePrismWithName ¶

func MakePrismWithName[S, A any](get OptionKleisli[S, A], rev func(A) S, name string) Prism[S, A]

func PrismFromOption ¶

func PrismFromOption[T any]() Prism[Option[T], T]

PrismFromOption creates a prism for extracting values from Option types. It provides a safe way to work with Option values, focusing on the Some case and handling the None case gracefully through the prism's GetOption behavior.

The prism's GetOption is the identity function - it returns the Option as-is. If the Option is Some(value), GetOption returns Some(value); if it's None, it returns None. This allows the prism to naturally handle the presence or absence of a value.

The prism's ReverseGet wraps a value into Some, always succeeding.

Type Parameters:

• T: The value type contained in the Option

Returns:

• A Prism[Option[T], T] that safely extracts values from Options

Example:

// Create a prism for extracting int values from Option[int]
optPrism := FromOption[int]()

// Extract from Some
someValue := option.Some(42)
result := optPrism.GetOption(someValue)  // Some(42)

// Extract from None
noneValue := option.None[int]()
result = optPrism.GetOption(noneValue)  // None[int]()

// Wrap value into Some
wrapped := optPrism.ReverseGet(100)  // Some(100)

// Use with Set to update Some values
setter := Set[Option[int], int](200)
result := setter(optPrism)(someValue)  // Some(200)
result = setter(optPrism)(noneValue)   // None[int]() (unchanged)

// Compose with other prisms for nested extraction
// Extract int from Option[Option[int]]
nestedPrism := Compose[Option[Option[int]], Option[int], int](
    FromOption[Option[int]](),
    FromOption[int](),
)
nested := option.Some(option.Some(42))
value := nestedPrism.GetOption(nested)  // Some(42)

Common use cases:

• Extracting values from optional fields
• Working with nullable data in a type-safe way
• Composing with other prisms to handle nested Options
• Filtering and transforming optional values in pipelines
• Converting between Option and other optional representations

Key insight: This prism treats Option[T] as a "container" that may or may not hold a value of type T. The prism focuses on the value inside, allowing you to work with it when present and gracefully handle its absence when not.

func PrismFromPredicate ¶

func PrismFromPredicate[S any](pred func(S) bool) Prism[S, S]

PrismFromPredicate creates a prism that matches values satisfying a predicate. GetOption returns Some(s) if the predicate is true, None otherwise. ReverseGet is the identity function (doesn't validate the predicate).

Parameters:

• pred: Predicate function to test values

Returns:

• A Prism[S, S] that filters based on the predicate

Example:

positivePrism := PrismFromPredicate(N.MoreThan(0))
value := positivePrism.GetOption(42)  // Some(42)
value = positivePrism.GetOption(-5)   // None[int]

func PrismId ¶

func PrismId[S any]() Prism[S, S]

PrismId returns an identity prism that focuses on the entire value. GetOption always returns Some(s), and ReverseGet is the identity function.

This is useful as a starting point for prism composition or when you need a prism that doesn't actually transform the value.

Example:

idPrism := PrismId[int]()
value := idPrism.GetOption(42)    // Some(42)
result := idPrism.ReverseGet(42)  // 42

func PrismSome ¶

func PrismSome[S, A any](soa Prism[S, Option[A]]) Prism[S, A]

PrismSome creates a prism that focuses on the PrismSome variant of an Option within a structure. It composes the provided prism (which focuses on an Option[A]) with a prism that extracts the value from PrismSome.

Type Parameters:

• S: The source type
• A: The value type within the Option

Parameters:

• soa: A prism that focuses on an Option[A] within S

Returns:

• A prism that focuses on the A value within PrismSome

Example:

type Config struct { Timeout Option[int] }
configPrism := MakePrism(...)  // Prism[Config, Option[int]]
timeoutPrism := PrismSome(configPrism)  // Prism[Config, int]
value := timeoutPrism.GetOption(Config{Timeout: PrismSome(30)})  // PrismSome(30)

func PrismComposePrism ¶

func PrismComposePrism[S, A, B any](ab Prism[A, B]) PrismOperator[S, A, B]

Compose composes two prisms to create a prism that focuses deeper into a structure. The resulting prism first applies the outer prism (S → A), then the inner prism (A → B).

Type Parameters:

• S: The outermost source type
• A: The intermediate type
• B: The innermost focus type

Parameters:

• ab: The inner prism (A → B)

Returns:

• A function that takes the outer prism (S → A) and returns the composed prism (S → B)

Example:

outerPrism := MakePrism(...)  // Prism[Outer, Inner]
innerPrism := MakePrism(...)  // Prism[Inner, Value]
composed := Compose[Outer](innerPrism)(outerPrism)  // Prism[Outer, Value]

func PrismIMap ¶

func PrismIMap[S any, AB ~func(A) B, BA ~func(B) A, A, B any](ab AB, ba BA) PrismOperator[S, A, B]

PrismIMap bidirectionally maps the focus type of a prism. It transforms a Prism[S, A] into a Prism[S, B] using two functions: one to map A → B and another to map B → A.

Type Parameters:

• S: The source type
• A: The original focus type
• B: The new focus type
• AB: Function type A → B
• BA: Function type B → A

Parameters:

• ab: Function to map from A to B
• ba: Function to map from B to A

Returns:

• A function that transforms Prism[S, A] to Prism[S, B]

Example:

intPrism := MakePrism(...)  // Prism[Result, int]
stringPrism := PrismIMap[Result](
    strconv.Itoa,
    func(s string) int { n, _ := strconv.Atoi(s); return n },
)(intPrism)  // Prism[Result, string]