fmtcoll

package
v0.12.2 Latest Latest
Warning

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

 Go to latest Published: Feb 16, 2024 License: AGPL-3.0 Imports: 9 Imported by: 0

Documentation

Overview

Package fmtcoll provides functions to format collections (such as slices and maps) into strings.

For better performance, all functions in this package are unsafe for concurrency unless otherwise specified.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func FormatGogoMapToString added in v0.7.2 

func FormatGogoMapToString[Key, Value any](
	m mapping.Map[Key, Value],
	format *MapFormat[Key, Value],
) (result string, err error)

FormatGogoMapToString formats the map m (of type github.com/donyori/gogo/container/mapping.Map) into a string with the specified format options.

It returns the result string and any error encountered.

If format is nil, it uses default format options as returned by NewDefaultMapFormat instead.

func FormatMapToString 

func FormatMapToString[M constraints.Map[Key, Value], Key comparable, Value any](
	m M,
	format *MapFormat[Key, Value],
) (result string, err error)

FormatMapToString formats the map m into a string with the specified format options.

It returns the result string and any error encountered.

If format is nil, it uses default format options as returned by NewDefaultMapFormat instead.

func FormatSequenceToString added in v0.7.2 

func FormatSequenceToString[Item any](
	s sequence.Sequence[Item],
	format *SequenceFormat[Item],
) (result string, err error)

FormatSequenceToString formats the sequence s into a string with the specified format options.

It returns the result string and any error encountered.

If format is nil, it uses default format options as returned by NewDefaultSequenceFormat instead.

func FormatSliceToString 

func FormatSliceToString[S constraints.Slice[Item], Item any](
	s S,
	format *SequenceFormat[Item],
) (result string, err error)

FormatSliceToString formats the slice s into a string with the specified format options.

It returns the result string and any error encountered.

If format is nil, it uses default format options as returned by NewDefaultSequenceFormat instead.

Example 
package main

import (
	"fmt"
	"io"

	"github.com/donyori/gogo/fmtcoll"
)

func main() {
	data := [][]*[2]int{
		{{0, 0}, {0, 1}, {0, 2}},
		{{1, 0}, nil, {1, 2}},
		{{2, 0}, {2, 1}, {2, 2}},
	}
	itemFormat := &fmtcoll.SequenceFormat[*[2]int]{
		CommonFormat: fmtcoll.CommonFormat{
			Separator: ", ",
		},
		FormatItemFn: func(w io.Writer, x *[2]int) error {
			var err error
			if x != nil {
				_, err = fmt.Fprintf(w, "(%d, %d)", x[0], x[1])
			} else if sw, ok := w.(io.StringWriter); ok {
				_, err = sw.WriteString(" <nil>")
			} else {
				_, err = w.Write([]byte(" <nil>"))
			}
			return err
		},
	}
	rowFormat := &fmtcoll.SequenceFormat[[]*[2]int]{
		CommonFormat: fmtcoll.CommonFormat{
			Separator:   ",\n    ",
			Prefix:      "\n    ",
			Suffix:      ",\n",
			PrependType: true,
			PrependSize: true,
		},
		FormatItemFn: func(w io.Writer, x []*[2]int) error {
			s, err := fmtcoll.FormatSliceToString(x, itemFormat)
			if err != nil {
				return err
			}
			if sw, ok := w.(io.StringWriter); ok {
				_, err = sw.WriteString(s)
			} else {
				_, err = w.Write([]byte(s))
			}
			return err
		},
	}

	s, err := fmtcoll.FormatSliceToString(data, rowFormat)
	if err != nil {
		panic(err) // handle error
	}
	fmt.Println(s)

}

Output:

([][]*[2]int,3)[
    [(0, 0), (0, 1), (0, 2)],
    [(1, 0),  <nil>, (1, 2)],
    [(2, 0), (2, 1), (2, 2)],
]

func MustFormatGogoMapToString added in v0.7.2 

func MustFormatGogoMapToString[Key, Value any](
	m mapping.Map[Key, Value],
	format *MapFormat[Key, Value],
) string

MustFormatGogoMapToString is like FormatGogoMapToString but panics when encountering an error.

func MustFormatMapToString 

func MustFormatMapToString[M constraints.Map[Key, Value], Key comparable, Value any](
	m M,
	format *MapFormat[Key, Value],
) string

MustFormatMapToString is like FormatMapToString but panics when encountering an error.

func MustFormatSequenceToString added in v0.7.2 

func MustFormatSequenceToString[Item any](
	s sequence.Sequence[Item],
	format *SequenceFormat[Item],
) string

MustFormatSequenceToString is like FormatSequenceToString but panics when encountering an error.

func MustFormatSliceToString 

func MustFormatSliceToString[S constraints.Slice[Item], Item any](
	s S,
	format *SequenceFormat[Item],
) string

MustFormatSliceToString is like FormatSliceToString but panics when encountering an error.

Types

type CommonFormat 

type CommonFormat struct {
	// Separator is the string inserted between every two items.
	//
	// Prefix is the string inserted before the first item.
	//
	// Suffix is the string inserted after the last item.
	//
	// Prefix and Suffix are used only if the collection is non-empty
	// and the collection content is not omitted.
	//
	// Separator is used only if the collection has at least two items
	// and the collection content is not omitted.
	Separator, Prefix, Suffix string

	// PrependType indicates whether to add
	// the collection type name before the content.
	//
	// PrependSize indicates whether to add
	// the collection size before the content.
	//
	// If PrependType is true and PrependSize is false,
	// the formatting result begins with the collection type name
	// wrapped in parentheses (e.g., "([]int)", "(map[string]int)").
	//
	// If PrependType is false and PrependSize is true,
	// the formatting result begins with the collection size
	// wrapped in parentheses (e.g., "(3)").
	//
	// If both PrependType and PrependSize are true,
	// the formatting result begins with the collection type name and size,
	// separated by a comma (','), and wrapped in parentheses
	// (e.g., "([]int,3)", "(map[string]int,3)").
	PrependType, PrependSize bool
}

CommonFormat contains the format options common to sequences and maps.

type FormatFunc 

type FormatFunc[T any] func(w io.Writer, x T) error

FormatFunc is a function to format x and write to w.

It returns any error encountered.

func FprintfToFormatFunc 

func FprintfToFormatFunc[T any](format string) FormatFunc[T]

FprintfToFormatFunc returns a FormatFunc that uses fmt.Fprintf to format x.

The parameter format is the format specifier passed to fmt.Fprintf. It must have exactly one verb for x.

type MapFormat 

type MapFormat[Key, Value any] struct {
	CommonFormat

	// FormatKeyFn is a function to format the key and write to w.
	// It returns any error encountered.
	//
	// If FormatKeyFn is nil, the key is omitted.
	// If both the key and value are omitted and the map is non-empty,
	// the content is printed as "...".
	FormatKeyFn FormatFunc[Key]

	// FormatValueFn is a function to format the value and write to w.
	// It returns any error encountered.
	//
	// If FormatValueFn is nil, the value is omitted.
	// If both the key and value are omitted and the map is non-empty,
	// the content is printed as "...".
	FormatValueFn FormatFunc[Value]

	// KeyValueLess is a function to report whether the key-value pair
	// (key1, value1) is less than (key2, value2).
	//
	// It is used to sort the key-value pairs in the map.
	//
	// It must describe a transitive ordering.
	// Note that floating-point comparison
	// (the < operator on float32 or float64 values)
	// is not a transitive ordering when not-a-number (NaN) values are involved.
	//
	// If KeyValueLess is nil, the key-value pairs may be in random order.
	KeyValueLess func(key1, key2 Key, value1, value2 Value) bool
}

MapFormat contains the format options for maps whose keys are of type Key and values are of type Value (e.g., map[Key]Value if Key is comparable, github.com/donyori/gogo/container/mapping.Map[Key, Value]).

The formatting result is as follows:

  • <TYPE-AND-SIZE> "<nil>", if the map is nil.
  • <TYPE-AND-SIZE> "{" <CONTENT> "}", if the map is non-nil (can be empty).

where <TYPE-AND-SIZE> is as follows:

  • "(" <TYPE> "," <SIZE> ")", if both PrependType and PrependSize are true.
  • "(" <TYPE> ")", if PrependType is true and PrependSize is false.
  • "(" <SIZE> ")", if PrependType is false and PrependSize is true.
  • "" (empty), if both PrependType and PrependSize are false.

and <CONTENT> is as follows:

  • <PREFIX> <ITEM-1> <SEPARATOR> <ITEM-2> <SEPARATOR> ... <SEPARATOR> <ITEM-N> <SUFFIX>, if the map has at least two key-value pairs and either FormatKeyFn or FormatValueFn is non-nil.
  • <PREFIX> <ITEM> <SUFFIX>, if the map has only one key-value pair and either FormatKeyFn or FormatValueFn is non-nil.
  • "...", if the map is non-empty and both FormatKeyFn and FormatValueFn are nil.
  • "" (empty), if the map is empty.

where <ITEM> (including <ITEM-1>, <ITEM-2>, ..., <ITEM-N>) is as follows:

  • <KEY> ":" <VALUE>, if both FormatKeyFn and FormatValueFn are non-nil.
  • <KEY>, if FormatKeyFn is non-nil and FormatValueFn is nil.
  • <VALUE>, if FormatKeyFn is nil and FormatValueFn is non-nil.

func NewDefaultMapFormat 

func NewDefaultMapFormat[Key, Value any]() *MapFormat[Key, Value]

NewDefaultMapFormat creates a new MapFormat with the default options as follows:

  • Separator: ","
  • Prefix: ""
  • Suffix: ""
  • PrependType: true
  • PrependSize: true
  • FormatKeyFn: FprintfToFormatFunc[Key]("%v")
  • FormatValueFn: FprintfToFormatFunc[Value]("%v")
  • KeyValueLess: nil

type SequenceFormat 

type SequenceFormat[Item any] struct {
	CommonFormat

	// FormatItemFn is a function to format the item x and write to w.
	// It returns any error encountered.
	//
	// If FormatItemFn is nil, the sequence content is omitted.
	// In this case, if the sequence is non-empty,
	// the content is printed as "...".
	FormatItemFn FormatFunc[Item]
}

SequenceFormat contains the format options for sequences whose items are of type Item (e.g., []Item, github.com/donyori/gogo/container/sequence.Sequence[Item]).

The formatting result is as follows:

  • <TYPE-AND-SIZE> "<nil>", if the sequence is nil.
  • <TYPE-AND-SIZE> "[" <CONTENT> "]", if the sequence is non-nil (can be empty).

where <TYPE-AND-SIZE> is as follows:

  • "(" <TYPE> "," <SIZE> ")", if both PrependType and PrependSize are true.
  • "(" <TYPE> ")", if PrependType is true and PrependSize is false.
  • "(" <SIZE> ")", if PrependType is false and PrependSize is true.
  • "" (empty), if both PrependType and PrependSize are false.

and <CONTENT> is as follows:

  • <PREFIX> <ITEM-1> <SEPARATOR> <ITEM-2> <SEPARATOR> ... <SEPARATOR> <ITEM-N> <SUFFIX>, if the sequence has at least two items and FormatItemFn is non-nil.
  • <PREFIX> <ITEM> <SUFFIX>, if the sequence has only one item and FormatItemFn is non-nil.
  • "...", if the sequence is non-empty and FormatItemFn is nil.
  • "" (empty), if the sequence is empty.

func NewDefaultSequenceFormat 

func NewDefaultSequenceFormat[Item any]() *SequenceFormat[Item]

NewDefaultSequenceFormat creates a new SequenceFormat with the default options as follows:

  • Separator: ","
  • Prefix: ""
  • Suffix: ""
  • PrependType: true
  • PrependSize: true
  • FormatItemFn: FprintfToFormatFunc[Item]("%v")

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.