typutil

func As ¶ added in v0.2.5

func As[T any](v any) (T, error)

As converts a value to the specified type T, with type conversion as needed.

This generic function provides a type-safe way to convert values between different types. It leverages the type conversion capabilities of Assign but returns the result as the requested type rather than modifying an existing variable.

Type Parameters:

• T: The target type to convert to

Parameters:

• v: The value to convert

Returns:

• The converted value as type T
• An error if the conversion cannot be performed

Example:

// Convert string to int
i, err := As[int]("42")  // i is 42

// Convert between struct types
type Person struct {Name string; Age int}
type User struct {Name string; Age string}

p := Person{Name: "Alice", Age: 30}
u, err := As[User](p)  // u is User{Name: "Alice", Age: "30"}

func AsBool ¶

func AsBool(v any) bool

AsBool converts any value to a boolean using an intuitive conversion strategy.

Conversion rules: - bool: used directly - numbers: true if non-zero, false if zero - strings: true if non-empty and not "0", false otherwise - bytes/buffer: true if length > 1 or not "0", false otherwise - maps/slices/collections: true if not empty, false otherwise - nil: false

This is useful when working with user inputs, configuration values, or any scenario where values of different types need to be interpreted as booleans.

func AsByteArray ¶ added in v0.1.14

func AsByteArray(v any) ([]byte, bool)

AsByteArray converts any value to a byte slice ([]byte) using flexible conversion rules.

It returns the converted byte slice and a boolean indicating success (true) or failure (false).

Conversion rules: - Strings: converted to UTF-8 byte representation - Byte slices: returned directly - Buffer types: contents extracted as bytes - Numeric types: converted to their binary representation (big-endian) - Booleans: true → [1], false → [0] - nil: returns nil - Complex/Float types: binary representation using encoding/binary - Other types: string representation as bytes, but marked as non-direct conversion (false)

This is useful for serialization, hashing, or when working with binary protocols.

func AsFloat ¶

func AsFloat(v any) (float64, bool)

AsFloat converts any value to a float64 using flexible type conversion rules.

It returns the converted value and a boolean indicating success (true) or failure (false).

Conversion rules: - Float types: directly converted to float64 - Integer types: converted to equivalent float64 - Unsigned integers: converted to equivalent float64 - Strings: parsed as floating point numbers (returns false if not a valid number) - nil: returns 0.0 - Other types: attempts conversion via AsInt as a fallback

This is useful for normalizing input data from various sources into consistent floating point values.

func AsInt ¶

func AsInt(v any) (int64, bool)

AsInt converts any value to an int64 using flexible type conversion rules.

It returns the converted value and a boolean indicating success (true) or failure (false).

Conversion rules: - Integer types: directly converted to int64 - Unsigned integers: converted to int64 (returns false if too large for int64) - Booleans: true → 1, false → 0 - Floating point: rounded to nearest integer (returns false if not a whole number) - Strings: parsed as integers (returns false if not a valid integer) - Byte slices: converted to string and parsed - Byte buffers: contents parsed as integers - nil: returns 0

This is useful for normalizing input data from various sources into consistent integer values.

func AsNumber ¶

func AsNumber(v any) (any, bool)

AsNumber converts any value to the most appropriate numeric type (int64, uint64, or float64).

It intelligently chooses the numeric type that best represents the input value: - Most integers are represented as int64 - Large unsigned integers (that don't fit in int64) are represented as uint64 - Decimal numbers are represented as float64 - String representations of numbers are parsed to the appropriate type

It returns the converted value (as interface{}) and a boolean indicating success (true) or failure (false).

This is particularly useful when you need to convert a value to a number, but don't know exactly which numeric type would be most appropriate.

func AsString ¶ added in v0.1.2

func AsString(v any) (string, bool)

AsString converts any value to a string using flexible conversion rules.

It returns the converted string and a boolean indicating success (true) or failure (false).

Conversion rules: - String types: used directly - Byte slices and buffers: converted to strings - Numeric types: formatted as base-10 strings - Booleans: true → "1", false → "0" - Other types: uses fmt.Sprintf("%v", value) but returns false to indicate non-direct conversion

This is useful when you need to display or serialize values of various types as strings.

func AsUint ¶

func AsUint(v any) (uint64, bool)

AsUint converts any value to a uint64 using flexible type conversion rules.

It returns the converted value and a boolean indicating success (true) or failure (false).

Conversion rules: - Integer types: converted to uint64 (returns false if negative) - Unsigned integers: directly converted to uint64 - Booleans: true → 1, false → 0 - Floating point: rounded to nearest integer (returns false if negative or not a whole number) - Strings: parsed as unsigned integers (returns false if not a valid unsigned integer) - nil: returns 0

This is useful for normalizing input data from various sources into consistent unsigned integer values.

func Assign ¶ added in v0.1.5

func Assign(dst, src any) error

Assign sets dst to the value of src, performing type conversion as needed.

This is the main entry point for the type conversion system in typutil. It handles automatic conversion between various Go types, including: - Primitive types (string, int, float, bool) - Pointers and interfaces - Slices and maps - Structs (using field names or JSON tags for matching) - Custom types that implement valueScanner or AssignableTo interfaces

For container types (slices, maps, structs), a shallow copy is performed.

Parameters:

• dst: A pointer to the destination value (must be a non-nil pointer)
• src: The source value to assign from

Returns:

• An error if the assignment cannot be performed, such as when:
• The destination is not a pointer
• The types are incompatible and cannot be converted
• The source value is invalid

Example:

// Convert between compatible types
var i int
err := Assign(&i, "42")  // i becomes 42

// Convert between struct types with matching fields
type Person struct {
    Name string
    Age int
}
type User struct {
    Name string
    Age string
}
p := Person{Name: "Alice", Age: 30}
var u User
err := Assign(&u, p)  // u becomes User{Name: "Alice", Age: "30"}

Note that unlike json.Unmarshal or similar functions, Assign requires a pointer to the destination value, not the destination value itself.

func AssignReflect ¶ added in v0.1.19

func AssignReflect(vdst, vsrc reflect.Value) error

AssignReflect assigns a value from one reflect.Value to another, with type conversion.

This is the reflection-based version of Assign that works directly with reflect.Value objects. It's used internally by the library and is also available for advanced use cases where you're already working with reflection.

Parameters:

• vdst: The destination reflect.Value
• vsrc: The source reflect.Value

Returns:

• An error if the assignment cannot be performed

This function handles unwrapping interface values, dealing with pointers, and finding the appropriate conversion function for the types involved.

func BaseType ¶ added in v0.1.4

func BaseType(v any) any

BaseType unwraps values to their underlying primitive types.

It performs the following conversions: - For custom types (e.g., `type CustomString string`), returns the underlying primitive (string) - For json.RawMessage, attempts to unmarshal the content - For reflect.Value, extracts the actual value - For pointers and interfaces, dereferences them to their underlying values - For numeric types, converts to their Go primitives (int64, uint64, float64, etc.)

Example:

type MyString string
var x MyString = "hello"
result := BaseType(x) // returns "hello" as a string, not MyString

This is useful when working with custom types and wanting to normalize them to standard Go types.

func Call ¶ added in v0.2.19

func Call[T any](s *Callable, ctx context.Context, arg ...any) (T, error)

Call invokes a Callable and returns a strongly typed result.

This generic function provides type safety for calling wrapped functions. It automatically converts the return value to the requested type T, which eliminates the need for type assertions in the calling code.

Parameters:

• s: The Callable to invoke
• ctx: The context to pass to the function
• arg: The arguments to pass to the function

Returns:

• A value of type T (the function's return value)
• An error if:
• The function call failed (see CallArg for possible errors)
• The function's return value could not be converted to type T

Example:

func add(a, b int) int { return a + b }
callable := Func(add)

// Get a strongly typed result
result, err := Call[int](callable, ctx, 5, 10) // result is an int, not an interface{}

// This will fail with ErrDifferentType
result, err := Call[string](callable, ctx, 5, 10) // err indicates type mismatch

Generic functions like this are particularly useful in code that needs to maintain type safety while still supporting flexible function calling patterns.

func DeepClone ¶ added in v0.2.9

func DeepClone[T any](v T) T

DeepClone performs a deep duplication of the provided argument, returning a newly created independent copy. All nested pointers, slices, maps, and structs are recursively cloned.

Circular references are handled correctly - if a structure contains pointers that form a cycle, the cloned structure will have equivalent cycles pointing to the cloned values.

Struct fields tagged with `clone:"-"` are skipped during deep cloning and retain their shallow-copied values. This is useful for fields like database connections, mutexes, or other resources that should not be duplicated:

type MyStruct struct {
    Data    []byte
    Conn    *sql.DB `clone:"-"` // will not be deep cloned
}

func DeepCloneReflect ¶ added in v0.2.9

func DeepCloneReflect(src reflect.Value) reflect.Value

DeepCloneReflect performs a deep duplication of the provided reflect.Value. See DeepClone for details on behavior.

func Equal ¶ added in v0.1.17

func Equal(a, b any) bool

Equal returns true if a and b are somewhat equal

func Flatten ¶ added in v0.2.8

func Flatten(a any) any

Flatten unwraps a value by removing all layers of pointers and interfaces, returning the underlying value.

This is particularly useful when working with values that might be wrapped in multiple layers of pointers or interfaces, and you want to get to the actual value.

Examples:

s := "hello"
ptr := &s
ptrptr := &ptr
Flatten(ptrptr)      // returns "hello" as a string

var nilPtr *string = nil
Flatten(nilPtr)      // returns nil

var iface interface{} = &s
Flatten(iface)       // returns "hello" as a string

The function preserves the nil status of values - if any pointer in the chain is nil, nil will be returned.

func FormatSize ¶ added in v0.2.22

func FormatSize(x uint64) string

FormatSize formats a byte size as a human-readable string with appropriate units.

This function converts a raw byte count into a formatted string using binary prefixes (KiB, MiB, GiB, etc.) according to IEC standards (powers of 1024).

The formatted string includes: - The integer part - A decimal point - Two decimal places - The appropriate binary unit (B, KiB, MiB, GiB, TiB, PiB, EiB)

For values less than 1024 bytes, the function returns a simple byte count without decimals.

Parameters:

• x: The size in bytes to format

Returns:

• A human-readable string representing the size

Examples:

• FormatSize(0) → "0 B"
• FormatSize(1023) → "1023 B"
• FormatSize(1024) → "1.00 KiB"
• FormatSize(1536) → "1.50 KiB"
• FormatSize(1048576) → "1.00 MiB"
• FormatSize(1073741824) → "1.00 GiB"

func IsNil ¶ added in v0.2.8

func IsNil(v any) bool

IsNil recursively checks if a value is nil, following pointers and interfaces to their underlying values.

This function provides a more robust nil check than the builtin `== nil` comparison, which only works for direct nil values. IsNil can detect "deeply nested" nil values, such as: - A nil pointer or interface - A pointer to a nil pointer - An interface containing a nil pointer - A pointer to an interface containing a nil pointer, etc.

It also correctly identifies nil channels, maps, slices, and functions.

Example:

var x *string            // x is nil
IsNil(x)                 // returns true

var y **string           // y points to a nil *string
IsNil(y)                 // returns true

var z interface{} = x    // z is an interface containing a nil pointer
IsNil(z)                 // returns true

For non-nillable types (like int, string, etc.), it always returns false.

func Math ¶ added in v0.1.16

func Math(mathop string, a, b any) (any, bool)

Math performs a mathematical operation on two values of any type and returns the result.

The function works by: 1. Converting both inputs to numeric types using AsNumber() 2. Determining the correct type of operation based on the numeric types 3. Applying the appropriate operation and returning the result

Parameters:

• mathop: The operation to perform as a string. Supported operations: "+", "-", "*", "/", "^", "%", "&", "|"
• a, b: The operands for the operation. Can be of any type that can be converted to a number

Returns:

• The result of the operation as int64, uint64, or float64 depending on the inputs
• A boolean indicating success (true) or failure (false)

Examples:

result, ok := Math("+", 40, 2)         // result = int64(42), ok = true
result, ok := Math("+", 40.5, 1.5)     // result = float64(42.0), ok = true
result, ok := Math("/", 84, 2)         // result = int64(42), ok = true
result, ok := Math("+", "40", "2")     // result = int64(42), ok = true
result, ok := Math("invalid", 1, 2)    // result = 0, ok = false

Notes:

• If either input has a float type, the result will be a float64
• Division by zero will cause a panic - it's recommended to check for zero divisors before calling
• Bitwise operations (^, %, &, |) return NaN when operating on floats

func OffsetGet ¶ added in v0.2.6

func OffsetGet(ctx context.Context, v any, offset string) (any, error)

OffsetGet returns v[offset] dealing with various case of figure. ctx will be passed to some methods handling it

func SetValidator ¶ added in v0.1.6

func SetValidator[T any](validator string, fnc func(T) error)

SetValidator registers a typed validation function with the given name.

This function provides a type-safe way to register validators. The validator function must accept a single argument of type T and return an error.

Parameters:

• validator: The name of the validator (used in struct tags)
• fnc: The validation function that checks values of type T

This function should typically be called in init() to register validators before they are used.

Example:

func init() {
    // Register a validator that ensures strings are not empty
    SetValidator("required", func(s string) error {
        if s == "" {
            return errors.New("value is required")
        }
        return nil
    })

    // Register a validator that ensures integers are positive
    SetValidator("positive", func(i int) error {
        if i <= 0 {
            return errors.New("value must be positive")
        }
        return nil
    })
}

func SetValidatorArgs ¶ added in v0.1.13

func SetValidatorArgs(validator string, fnc any)

SetValidatorArgs registers a validation function that may accept additional arguments.

Unlike SetValidator, this function accepts any function type as long as it takes at least one argument (the value to validate) and returns an error. Additional arguments can be specified in the validator tag after an equals sign.

Parameters:

• validator: The name of the validator (used in struct tags)
• fnc: The validation function, which must:
• Take at least one argument (the value to validate)
• Return an error (or nil if validation passes)

Example:

func init() {
    // Register a validator that ensures strings have a minimum length
    SetValidatorArgs("minlength", func(s string, minLen int) error {
        if len(s) < minLen {
            return fmt.Errorf("must be at least %d characters long", minLen)
        }
        return nil
    })
}

// Then use it in a struct tag:
type User struct {
    Password string `validator:"minlength=8"` // Password must be at least 8 characters
}

Panics if:

• fnc is not a function
• fnc does not accept at least one argument

func StrictArgs ¶ added in v0.2.24

func StrictArgs(c *Callable)

StrictArgs is a functional option for Func that enforces strict type checking of arguments. When enabled, arguments passed to the function must match the expected types exactly, rather than using the more flexible conversion via the Assign function.

Example:

// Without StrictArgs, "42" would be converted to int(42)
f := Func(myIntFunc)                 // Allows "42" to be passed to an int parameter
f2 := Func(myIntFunc, StrictArgs)    // Requires an actual int, rejects "42"

func Validate ¶ added in v0.1.10

func Validate(obj any) error

Validate checks if a struct meets all validation rules defined in its field tags.

This function processes all fields in a struct that have "validator" tags and runs the appropriate validation functions on them. If any validation fails, an error is returned with details about which field failed and why.

Parameters:

• obj: A pointer to the struct to validate. Using a pointer is required so that validators can potentially modify values during validation.

Returns:

• nil if all validations pass
• An error if any validation fails, formatted as "on field X: error details"
• ErrStructPtrRequired if obj is not a pointer to a struct

Example:

type User struct {
    Name     string `validator:"required"`
    Email    string `validator:"required,email"`
    Password string `validator:"minlength=8"`
}

user := &User{Name: "Alice", Email: "invalid", Password: "123"}
err := Validate(user) // Returns error: "on field Email: invalid email format"

Validations are applied in the order they appear in the tag, from left to right. If a field has no validator tag or the tag is empty, it is not validated.