convert

package
v0.35.0 Latest Latest
Warning

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

 Go to latest Published: Aug 18, 2026 License: Apache-2.0 Imports: 10 Imported by: 33

README

convert

Best-effort coercion between arbitrary Go types. Scalar converters (Bool, Int, Int32, Int64, Float, String, Time, Bytes) plus container converters (SliceOfString, SliceOfInt, MapOfAny, …) and generic pointer helpers (Pointer[T], Element[T]). Each scalar has plain, Default, and …Ok variants. Part of rosetta.

Go Reference

What matters here

  • The …Ok suffix means "lossless?", NOT "succeeded?". StringOk/IntOk/etc. return (value, ok) where ok is true only when the converted value round-trips back to the original input. A conversion that rounds, truncates, or falls back to the default returns a usable value with ok=false. Use the Ok form when you must distinguish an exact conversion from a lossy one.
  • String formats floats with a FIXED two decimal places — this is lossy. convert.String(3.14159) yields "3.14", and StringOk reports ok=false because it doesn't round-trip. This bites anywhere a float is rendered through convert.String (and transitively through mapof/hannibal string getters). It is intentional, not a bug; reach for strconv.FormatFloat directly when you need full precision.
  • The plain and Default forms swallow the lossless flag. String(v) is StringOk(v, "") discarding the bool; StringDefault(v, d) substitutes d only when the value can't be converted at all. Neither tells you the result was rounded — only the Ok form does.
  • Converters recognize rosetta's getter interfaces (Booler, Inter, Floater, Stringer, Hexer, plus io.Reader and reflect.Value). A type that implements one is converted via that method, so custom types flow through convert without a dedicated case. The type switch is order-sensitive — adding a case can change which interface a value matches first.
  • For typed pointer/deref helpers prefer convert.Pointer[T]/Element[T] over the reflection-based pointer package when the type is known at compile time; convert owns the generic, type-safe versions.

Documentation

Overview

Package convert converts values from one type into another, accepting generic input and producing a specific Go type with sensible defaults.

Most conversions come in three shapes. The bare form (Int, String, Bool) always returns a value, falling back to the zero value when the input cannot be converted. The Default form substitutes a caller-supplied fallback instead. The Ok form returns that same value alongside a boolean reporting whether the conversion actually succeeded, for callers that need to tell "absent" from "converted to zero".

Conversions reach through pointers, interfaces, and the small accessor interfaces shared with the compare package, so a type that can describe itself as an int or a string is converted through that description rather than by reflection over its fields.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BaseTypeOK added in v0.24.1 

func BaseTypeOK(value any) (any, bool)

BaseTypeOK attempts to convert a value into a base type (bool, int, float, string, slice, map). The boolean result value returns TRUE if successful. FALSE otherwise

func Bool 

func Bool(value any) bool

Bool forces a conversion from an arbitrary value into a boolean. If the value cannot be converted, then the default value for the type is used.

func BoolDefault 

func BoolDefault(value any, defaultValue bool) bool

BoolDefault forces a conversion from an arbitrary value into a bool. if the value cannot be converted, then the default value is used.

func BoolOk 

func BoolOk(value any, defaultValue bool) (bool, bool)

BoolOk converts an arbitrary value (passed in the first parameter) into a boolean, somehow, no matter what. The first result is the final converted value, or the default value (passed in the second parameter) The second result is TRUE if the conversion was lossless (the converted value round-trips back to the original input), and FALSE otherwise.

Conversion Rules: Nils return default value and Ok=false Bools are passed through with Ok=true Ints and Floats of exactly 0 or 1 map losslessly to false/true with Ok=true; any other numeric value is lossy and returns Ok=false String values of "true" and "false" convert losslessly with Ok=true All other strings return the default value, with Ok=false A slice of length 1 carries the Ok of its single element; an empty or longer slice is lossy (Ok=false) Known interfaces (Booler, Inter, Floater, Stringer) are handled like their corresponding types All other values return the default value with Ok=false

func Bytes added in v0.5.4 

func Bytes(value any) []byte

Bytes forces a conversion from an arbitrary value into a slice of bytes.

func Element added in v0.22.4 

func Element(original any) any

Element defreferences a pointer, if necessary, and returns the underlying value

func Float 

func Float(value any) float64

Float forces a conversion from an arbitrary value into a float64. If the value cannot be converted, then the zero value for the type (false) is used.

func FloatDefault 

func FloatDefault(value any, defaultValue float64) float64

FloatDefault forces a conversion from an arbitrary value into a float64. if the value cannot be converted, then the default value is used.

func FloatOk 

func FloatOk(value any, defaultValue float64) (float64, bool)

FloatOk converts an arbitrary value (passed in the first parameter) into a float64, no matter what. The first result is the final converted value, or the default value (passed in the second parameter) The second result is TRUE if the conversion was lossless (the converted value round-trips back to the original input), and FALSE otherwise.

Conversion Rules: Nils return default value and Ok=false Bools map losslessly to 0/1 with Ok=true Floats and small integers convert with Ok=true; integer magnitudes above 2^53 cannot be represented exactly and are lossy (Ok=false) String values are parsed as a float64; a clean parse is lossless (Ok=true), otherwise the default value is returned with Ok=false A slice of length 1 carries the Ok of its single element; an empty or longer slice is lossy (Ok=false) Known interfaces (Inter, Floater, Stringer) are handled like their corresponding types. All other values return the default value with Ok=false

func HTTPHeader added in v0.22.2 

func HTTPHeader(value any) http.Header

HTTPHeader converts a data structure into a http.Header object, which is a specialized instance of a map[string][]string.

func HTTPHeaderOk added in v0.22.2 

func HTTPHeaderOk(value any) (http.Header, bool)

HTTPHeaderOk converts a data structure into a http.Header object, which is a specialized instance of a map[string][]string. It returns TRUE if the conversion was successful, and FALSE otherwise.

func Int 

func Int(value any) int

Int forces a conversion from an arbitrary value into an int. If the value cannot be converted, then the zero value for the type (0) is used.

func Int32 added in v0.25.14 

func Int32(value any) int32

Int32 forces a conversion from an arbitrary value into an int. If the value cannot be converted, then the zero value for the type (0) is used.

func Int32Default added in v0.25.14 

func Int32Default(value any, defaultValue int32) int32

Int32Default forces a conversion from an arbitrary value into a int. if the value cannot be converted, then the default value is used.

func Int32Ok added in v0.25.14 

func Int32Ok(value any, defaultValue int32) (int32, bool)

Int32Ok converts an arbitrary value (passed in the first parameter) into an int32, no matter what. The first result is the final converted value, or the default value (passed in the second parameter) The second result is TRUE if the conversion was lossless (the converted value round-trips back to the original input), and FALSE otherwise.

Conversion Rules: Nils return default value and Ok=false Bools map losslessly to 0/1 with Ok=true Int32s are returned directly with Ok=true Floats with no fractional part convert with Ok=true; a fractional part is lossy (Ok=false) Out-of-range values are clamped to the int32 bounds and reported as lossy (Ok=false) String values are parsed as an int; a clean parse is lossless (Ok=true), otherwise the default value is returned with Ok=false A slice of length 1 carries the Ok of its single element; an empty or longer slice is lossy (Ok=false) Known interfaces (Inter, Floater, Stringer) are handled like their corresponding types. All other values return the default value with Ok=false

func Int64 

func Int64(value any) int64

Int64 forces a conversion from an arbitrary value into an int. If the value cannot be converted, then the zero value for the type (0) is used.

func Int64Default 

func Int64Default(value any, defaultValue int64) int64

Int64Default forces a conversion from an arbitrary value into a int. if the value cannot be converted, then the default value is used.

func Int64Ok 

func Int64Ok(value any, defaultValue int64) (int64, bool)

Int64Ok converts an arbitrary value (passed in the first parameter) into an int64, no matter what. The first result is the final converted value, or the default value (passed in the second parameter) The second result is TRUE if the conversion was lossless (the converted value round-trips back to the original input), and FALSE otherwise.

Conversion Rules: Nils return default value and Ok=false Bools map losslessly to 0/1 with Ok=true Int64s are returned directly with Ok=true Floats with no fractional part convert with Ok=true; a fractional part is lossy (Ok=false) Out-of-range values are clamped to the int64 bounds and reported as lossy (Ok=false) String values are parsed as an int; a clean parse is lossless (Ok=true), otherwise the default value is returned with Ok=false A slice of length 1 carries the Ok of its single element; an empty or longer slice is lossy (Ok=false) Known interfaces (Inter, Floater, Stringer) are handled like their corresponding types. All other values return the default value with Ok=false

func IntBitsizeOk added in v0.27.0 

func IntBitsizeOk(value any, defaultValue int, bitSize int) (result any, lossless bool, inBounds bool)

IntBitsizeOk converts an arbitrary value into an integer of the requested bit size (8, 16, 32, 64, or any other value for a platform-width int), clamping out-of-range values to that width. "lossless" is TRUE when the underlying numeric conversion round-trips exactly; "inBounds" is TRUE when the value fit the bit size without being clamped.

func IntDefault 

func IntDefault(value any, defaultValue int) int

IntDefault forces a conversion from an arbitrary value into a int. if the value cannot be converted, then the default value is used.

func IntOk 

func IntOk(value any, defaultValue int) (int, bool)

IntOk converts an arbitrary value (passed in the first parameter) into an int, no matter what. The first result is the final converted value, or the default value (passed in the second parameter). The second result is TRUE if the conversion was lossless (the converted value round-trips back to the original input), and FALSE otherwise.

Conversion Rules: Nils return default value and Ok=false Bools map losslessly to 0/1 with Ok=true Ints are returned directly with Ok=true Floats with no fractional part convert with Ok=true; a fractional part is lossy (Ok=false) Out-of-range values are clamped to the int bounds and reported as lossy (Ok=false) String values are parsed as an int; a clean parse is lossless (Ok=true), otherwise the default value is returned with Ok=false A slice of length 1 carries the Ok of its single element; an empty or longer slice is lossy (Ok=false) Known interfaces (Inter, Floater, Stringer) are handled like their types. All other values return the default value with Ok=false

func Interface 

func Interface(value any) any

Interface returns the value of a reflect.Value. If the value is not already a reflect.Value, then it is returned as-is.

func IsMap added in v0.19.1 

func IsMap(value any) bool

IsMap returns TRUE if the value is a map (Uses Reflection)

func IsSlice added in v0.19.1 

func IsSlice(value any) bool

IsSlice returns TRUE if the value is a slice or array (Uses Reflection)

func JoinString added in v0.5.3 

func JoinString(value any, delimiter string) string

JoinString converts the value into a string. If the value is a slice ([]string or []any), then the values are joined with the specified delimiter. If the value is not a slice, then it is converted to a string using the String() function.

func MapOfAny added in v0.14.0 

func MapOfAny(value any) map[string]any

MapOfAny attempts to convert the generic value into a map[string]any

func MapOfAnyOk added in v0.14.0 

func MapOfAnyOk(value any) (map[string]any, bool)

MapOfAnyOk attempts to convert the generic value into a map[string]any The boolean result value returns TRUE if successful. FALSE otherwise

func MapOfInt added in v0.25.14 

func MapOfInt(value any) map[string]int

MapOfInt attempts to convert the generic value into a map[string]string

func MapOfInt32 added in v0.25.14 

func MapOfInt32(value any) map[string]int32

MapOfInt32 attempts to convert the generic value into a map[string]string

func MapOfInt32Ok added in v0.25.14 

func MapOfInt32Ok(value any) (map[string]int32, bool)

MapOfInt32Ok attempts to convert the generic value into a map[string]string The boolean result value returns TRUE if successful. FALSE otherwise

func MapOfIntOk added in v0.25.14 

func MapOfIntOk(value any) (map[string]int, bool)

MapOfIntOk attempts to convert the generic value into a map[string]string The boolean result value returns TRUE if successful. FALSE otherwise

func MapOfSliceOfString added in v0.22.2 

func MapOfSliceOfString(value any) map[string][]string

MapOfSliceOfString converts the given value to a map[string][]string. If conversion is not possible, then an empty map is returned.

func MapOfSliceOfStringOk added in v0.22.2 

func MapOfSliceOfStringOk(value any) (map[string][]string, bool)

MapOfSliceOfStringOk converts the given value to a map[string][]string. It returns TRUE if the conversion was successful. If conversion is not possible, then it returns an empty map and FALSE.

func MapOfString added in v0.19.0 

func MapOfString(value any) map[string]string

MapOfString attempts to convert the generic value into a map[string]string

func MapOfStringOk added in v0.19.0 

func MapOfStringOk(value any) (map[string]string, bool)

MapOfStringOk attempts to convert the generic value into a map[string]string The boolean result value returns TRUE if successful. FALSE otherwise

func NullBool 

func NullBool(value any) null.Bool

NullBool converts a value into a nullable value. The value is only set if the input value is a natural match for this data type.

func NullFloat 

func NullFloat(value any) null.Float

NullFloat converts a value into a nullable value. The value is only set if the input value is a natural match for this data type.

func NullInt 

func NullInt(value any) null.Int

NullInt converts a value into a nullable value. The value is only set if the input value is a natural match for this data type.

func NullInt64 

func NullInt64(value any) null.Int64

NullInt64 converts a value into a nullable value. The value is only set if the input value is a natural match for this data type.

func Pointer added in v0.22.4 

func Pointer[T any](original T) *T

Pointer returns a pointer to the original value

func ReflectType added in v0.6.0 

func ReflectType(value any) reflect.Type

ReflectType returns the reflect.Type of the given argument. If the argument is already a reflect.Type, then it is returned as-is.

func ReflectValue added in v0.6.0 

func ReflectValue(value any) reflect.Value

ReflectValue returns the reflect.Value of the given argument. If the argument is already a reflect.Value, then it is returned as-is.

func SliceLength added in v0.6.0 

func SliceLength(value any) int

SliceLength returns the length of any slice

func SliceOfAny added in v0.14.0 

func SliceOfAny(value any) []any

SliceOfAny converts the value into a slice of any. It works with any, []any, []string, []int, []float64, string, int, and float64 values. If the passed value cannot be converted, then an empty slice is returned.

func SliceOfAnyOk added in v0.17.0 

func SliceOfAnyOk(value any) ([]any, bool)

SliceOfAnyOk converts the value into a slice of any. It works with any, []any, []string, []int, []float64, string, int, and float64 values. It returns TRUE if the conversion was successful, and FALSE otherwise.

func SliceOfFloat 

func SliceOfFloat(value any) []float64

SliceOfFloat converts the value into a slice of floats. It works with any, []any, []float64, and float64 values. If the passed value cannot be converted, then an empty slice is returned.

func SliceOfFloatOk added in v0.22.2 

func SliceOfFloatOk(value any) ([]float64, bool)

SliceOfFloatOk converts the value into a slice of floats. It works with any, []any, []float64, and float64 values. It returns TRUE if the conversion was successful, and FALSE otherwise.

func SliceOfInt 

func SliceOfInt(value any) []int

SliceOfInt converts the value into a slice of ints. It works with any, []any, []string, []int, and int values. If the passed value cannot be converted, then an empty slice is returned.

func SliceOfInt64 added in v0.10.0 

func SliceOfInt64(value any) []int64

SliceOfInt64 converts the value into a slice of int64s. It works with any, []any, []string, []int, and int values. If the passed value cannot be converted, then an empty slice is returned.

func SliceOfInt64Ok added in v0.22.2 

func SliceOfInt64Ok(value any) ([]int64, bool)

SliceOfInt64Ok converts the value into a slice of int64s. It works with float64, int, int64, string, and []any, []float64, []int, []int64, and []string values. It returns TRUE if the conversion was successful, and FALSE otherwise.

func SliceOfIntOk added in v0.22.2 

func SliceOfIntOk(value any) ([]int, bool)

SliceOfIntOk converts the value into a slice of ints. It works with float, int, int, string, and []any, []float, []int, []int, and []string values. It returns TRUE if the conversion was successful, and FALSE otherwise.

func SliceOfMap 

func SliceOfMap(value any) []map[string]any

SliceOfMap converts the value into a slice of map[string]any. It works with []any, []map[string]any. If the passed value cannot be converted, then an empty slice is returned.

func SliceOfMapOk added in v0.22.2 

func SliceOfMapOk(value any) ([]map[string]any, bool)

SliceOfMapOk converts the value into a slice of map[string]any. It works with []any, []map[string]any, []map[string]string, and []MapOfAnyGetter. It returns TRUE if the conversion was successful, and FALSE otherwise.

func SliceOfString 

func SliceOfString(value any) []string

SliceOfString converts the value into a slice of strings. It works with any, []any, []string, and string values. If the passed value cannot be converted, then an empty slice is returned.

func SliceOfStringOk added in v0.22.2 

func SliceOfStringOk(value any) ([]string, bool)

SliceOfStringOk converts the value into a slice of strings. It works with any, []any, []string, and string values. It returns TRUE if the value was converted successfullt, and FALSE otherwise.

func String 

func String(value any) string

String forces a conversion from an arbitrary value into an string. If the value cannot be converted, then the default value for the type is used.

func StringDefault 

func StringDefault(value any, defaultValue string) string

StringDefault forces a conversion from an arbitrary value into a string. if the value cannot be converted, then the default value is used.

func StringOk 

func StringOk(value any, defaultValue string) (string, bool)

StringOk converts an arbitrary value (passed in the first parameter) into a string, no matter what. The first result is the final converted value, or the default value (passed in the second parameter) The second result is TRUE if the conversion was lossless (the converted value round-trips back to the original input), and FALSE otherwise.

Conversion Rules: Nils return default value and Ok=false Bools are formatted as "true" or "false" losslessly, with Ok=true Ints are formatted as decimal strings losslessly, with Ok=true Floats are formatted with two decimal places; Ok=true only when that two-decimal string parses back to the original value, otherwise the rounding is lossy (Ok=false) Strings are passed through directly, with Ok=true A slice of length 1 carries the Ok of its single element; an empty or longer slice is lossy (Ok=false) Known interfaces (Inter, Floater, Stringer) are handled like their corresponding types. All other values return the default value with Ok=false

func Time added in v0.16.1 

func Time(value any) time.Time

Time converts the value into a time.Time. It works with time.Time, Timer, ToTimer, string, int, and int64 values. If the passed value cannot be converted, then the zero time is returned.

func TimeDefault added in v0.16.1 

func TimeDefault(value any, defaultValue time.Time) time.Time

TimeDefault converts the value into a time.Time. It works with time.Time, Timer, ToTimer, string, int, and int64 values. If the passed value cannot be converted, then the defaultValue is returned.

func TimeOk added in v0.16.1 

func TimeOk(value any, defaultValue time.Time) (time.Time, bool)

TimeOk converts the value into a time.Time. It works with time.Time, Timer, ToTimer, string, int, and int64 values. It returns TRUE if the conversion was successful, and FALSE otherwise.

func TimeWithLocale added in v0.24.5 

func TimeWithLocale(value string, layouts ...string) (time.Time, bool)

TimeWithLocale parses a string into a time.Time using the provided locale(s). If no locale is provided, it will use a list of common layouts, including RFE3339, RFC3339 (nano), HTTP timestamps, and others.

func URLValues added in v0.22.1 

func URLValues(value any) url.Values

URLValues converts a data structure into a url.Values object, which is a specialized instance of a map[string][]string.

func URLValuesOk added in v0.22.1 

func URLValuesOk(value any) (url.Values, bool)

URLValuesOk converts a data structure into a url.Values object, which is a specialized instance of a map[string][]string. It returns TRUE if the conversion was successful, and FALSE otherwise.

Types

type Booler 

type Booler interface {

	// Bool returns the bool value of the underlying object
	Bool() bool
}

Booler interface wraps the Bool() method that enables custom types to convert themselves to bool.

type Floater 

type Floater interface {

	// Float returns the float64 value of the underlying object
	Float() float64
}

Floater interface wraps the Float() method that enables custom types to convert themselves to float64.

type Hexer 

type Hexer interface {

	// Hex returns the hexadecimal string value of the underlying object
	Hex() string
}

Hexer interface wraps the Hex() method that enables a custom type to convert itself into a hexadecimal string

type Int64er added in v0.22.2 

type Int64er interface {

	// Int64 returns the int64 value of the underlying object
	Int64() int64
}

Int64er interface wraps the Int64() method that enables custom types to convert themselves to int64s.

type Inter 

type Inter interface {

	// Int returns the int value of the underlying object
	Int() int
}

Inter interface wraps the Int() method that enables custom types to convert themselves to ints.

type LengthGetter added in v0.13.1 

type LengthGetter interface {

	// Length returns the length of the array or map
	Length() int
}

LengthGetter interface wraps the Length() method that returns the length of an array or map

type MapOfAnyGetter added in v0.22.2 

type MapOfAnyGetter interface {

	// MapOfAny returns the underlying data structure as a plain map[string]any
	MapOfAny() map[string]any
}

MapOfAnyGetter wraps the MapOfAny() method that returns a data structure as a MapOfAny

type Nuller 

type Nuller interface {

	// IsNull returns TRUE if the underlying value is null
	IsNull() bool
}

Nuller wraps the IsNull interface (implemented by the null.* package) that enables custom types to declare that their value is null (zero)

type SliceOfStringer added in v0.25.11 

type SliceOfStringer interface {

	// SliceOfString returns the underlying data structure as a slice of strings
	SliceOfString() []string
}

SliceOfStringer interface wraps the SliceOfStringer() method that enables a custom type to convert itself into a slice of strings

type Stringer 

type Stringer interface {

	// String returns the string value of the underlying object
	String() string
}

Stringer interface wraps the String() method that enables a custom type to convert themselves into strings.

type Timer added in v0.19.1 

type Timer interface {

	// Time returns the time.Time value of the underlying object
	Time() time.Time
}

Timer interface wraps the Time() method that returns the time.Time value of the underlying object

type ToTimer added in v0.24.5 

type ToTimer interface {

	// ToTime returns the time.Time value of the underlying object
	ToTime() time.Time
}

ToTimer interface wraps the ToTime() method that returns the time.Time value of the underlying object. This is a cheap hack for instances where we can't use the Timer interface

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.