strconvert

func Parse ¶

func Parse(s string, v reflect.Value, optFns ...func(*Options)) error

Parse parses the string s and stores the result in the underlying Go value pointed to by v. If v is addressable (as defined by the reflect package), Parse returns an ErrInvalidParseArgument.

Parse is the inverse operation of calling Stringify with the same options and complementing custom parsers/stringifiers. The following types for the underlying Go value of v are supported:

• Types registered using the WithParser option
• Types implementing encoding.TextUnmarshaler
• Types implementing encoding.BinaryUnmarshaler
• ~string
• ~int, ~int8, ~int16, ~int32, ~int64
• time.Duration
• ~uint, ~uint8, ~uint16, ~uint32, ~uint64
• ~float32, ~float64
• ~complex64, ~complex128
• ~bool
• Any pointer to the above types
• slices, arrays and maps of any of the above types

Parse errors for any unsupported type. More types may be be supported in the future.

func Stringify ¶

func Stringify(v reflect.Value, optFns ...func(*Options)) (string, error)

Stringify converts v to a string.

The following types for the underlying Go value of v are supported:

• Types registered using the WithStringifier option
• Types implementing encoding.TextMmarshaler
• Types implementing encoding.BinaryMarshaler
• ~string
• ~int, ~int8, ~int16, ~int32, ~int64
• time.Duration
• ~uint, ~uint8, ~uint16, ~uint32, ~uint64
• ~float32, ~float64
• ~complex64, ~complex128
• ~bool
• Any pointer to the above types
• slices, arrays and maps of any of the above types

Stringify errors for any unsupported type. More types may be be supported in the future.

Float and complex types are formatted using the format byte 'f' and precision -1. See the documentation for strconv.FormatFloat. Override this behaviour by registering custom stringifiers.

Map values are sorted before formatted into the final string representation, ensuring consistent and predictable output. By default, keys and values are separated using colons (":") and key, value pairs are separated using semicolons (";").

By default, slice and array elements are separated using semicolons (";").

func WithElementSeparator ¶

func WithElementSeparator(r rune) func(*Options)

WithElementSeparator overrides the default element separator used for parsing/stringifying slices, arrays and maps.

func WithKeySeparator ¶

func WithKeySeparator(r rune) func(*Options)

WithKeySeparator override the default key separator used for parsing/stringifying key, value pairs in maps.

func WithParser ¶

func WithParser[T any](fn func(s string) (T, error)) func(*Options)

WithParser registers a custom parser function for a concrete type.

Parse errors if return type T is an interface, channel, function, map, uintptr, or unsafe.Pointer. More types may be be supported in the future.

package main

import (
	"fmt"
	"strings"

	"github.com/nahojer/strconvert"
)

func main() {
	// Extend Parse's type support by registering a parser for our custom type.
	type PrefixedValue struct {
		Value  string
		Prefix string
	}
	strconvert.WithParser(func(s string) (PrefixedValue, error) {
		prefix := "--"
		value, found := strings.CutPrefix(s, prefix)
		if !found {
			return PrefixedValue{}, fmt.Errorf("failed to parse PrefixedValue from %q", s)
		}
		return PrefixedValue{Value: value, Prefix: prefix}, nil
	})
}

Output:

func WithStringifier ¶

func WithStringifier[T any](fn func(v T) (string, error)) func(*Options)

WithStringifier registers a custom stringifier function for a concrete type.

Stringify errors if argument type T is an interface, channel, function, map, uintptr, or unsafe.Pointer. More types may be be supported in the future.

package main

import (
	"strconv"

	"github.com/nahojer/strconvert"
)

func main() {
	// Override how float64 values is formatted.
	strconvert.WithStringifier(func(f float64) (string, error) {
		return strconv.FormatFloat(f, 'E', 6, 64), nil
	})

	// Do the same for pointer float64 values.
	strconvert.WithStringifier(func(f *float64) (string, error) {
		if f == nil {
			return strconv.FormatFloat(0, 'E', 6, 64), nil
		}
		return strconv.FormatFloat(*f, 'E', 6, 64), nil
	})

	// Extend Stringify's type support by registering a stringifier for our
	// custom type.
	type PrefixedValue struct {
		Value  string
		Prefix string
	}
	strconvert.WithStringifier(func(pv PrefixedValue) (string, error) {
		return pv.Prefix + pv.Value, nil
	})
}

Output: