diff --git a/vimebu_func.go b/vimebu_func.go index 520d9d2..699fcf3 100644 --- a/vimebu_func.go +++ b/vimebu_func.go @@ -5,10 +5,13 @@ import ( "strings" ) -// LabelCallback TODO: type LabelCallback func() (name, value string, escapeQuote bool) -// WithLabel TODO: +// WithLabel appends a pair of label name and label value to the builder. +// Unlike [vimebu.WithLabelQuote], quotes inside the label value will not be escaped. +// It's better suited for a label value where you control the input (either it is already sanitized, or it comes from a const or an enum for example). +// +// Panics if the label name or label value contain more than [vimebu.LabelNameMaxLen] or [vimebu.LabelValueMaxLen] bytes respectively. func WithLabel(name, value string) LabelCallback { if len(name) > LabelNameMaxLen { panic("label name contains too many bytes") @@ -23,7 +26,10 @@ func WithLabel(name, value string) LabelCallback { } } -// WithLabelCond TODO: +// WithLabelCond is a wrapper around [vimebu.WithLabel]. +// It allows you to conditionally add a label depending on the output of a predicate function. +// +// Panics if the label name or label value contain more than [vimebu.LabelNameMaxLen] or [vimebu.LabelValueMaxLen] bytes respectively. func WithLabelCond(fn func() bool, name, value string) LabelCallback { if fn() { return WithLabel(name, value) @@ -31,7 +37,9 @@ func WithLabelCond(fn func() bool, name, value string) LabelCallback { return WithLabel("", "") } -// WithLabelQuote TODO: +// WithLabelQuote appends a pair of label name and label value to the builder. Quotes inside the label value will be escaped. +// +// Panics if the label name or label value contain more than [vimebu.LabelNameMaxLen] or [vimebu.LabelValueMaxLen] bytes respectively. func WithLabelQuote(name, value string) LabelCallback { if len(name) > LabelNameMaxLen { panic("label name contains too many bytes") @@ -46,7 +54,10 @@ func WithLabelQuote(name, value string) LabelCallback { } } -// WithLabelQuoteCond TODO: +// WithLabelQuoteCond is a wrapper around [vimebu.WithLabelQuote]. +// It allows you to conditionally add a label depending on the output of a predicate function. +// +// Panics if the label name or label value contain more than [vimebu.LabelNameMaxLen] or [vimebu.LabelValueMaxLen] bytes respectively. func WithLabelQuoteCond(fn func() bool, name, value string) LabelCallback { if fn() { return WithLabelQuote(name, value) @@ -55,6 +66,9 @@ func WithLabelQuoteCond(fn func() bool, name, value string) LabelCallback { } // BuilderFunc is used to efficiently build a VictoriaMetrics metric. +// It's backed by a bytes.Buffer to minimize memory copying. +// +// Panics if the name is empty, contains more than [vimebu.MetricNameMaxLen] bytes or if it contains a double quote. func BuilderFunc(name string, labels ...LabelCallback) string { ln := len(name) if ln == 0 { diff --git a/vimebu_func_test.go b/vimebu_func_test.go index 6d51a5c..d2ac66a 100644 --- a/vimebu_func_test.go +++ b/vimebu_func_test.go @@ -6,7 +6,7 @@ import ( "github.com/stretchr/testify/require" ) -func handleTestCaseFn(t *testing.T, tc testCase) { +func handleTestCaseFunc(t *testing.T, tc testCase) { labels := make([]LabelCallback, 0, len(tc.input.labels)) for _, label := range tc.input.labels { @@ -21,16 +21,16 @@ func handleTestCaseFn(t *testing.T, tc testCase) { require.Equal(t, tc.expected, result) } -func TestBuilderFn(t *testing.T) { +func TestBuilderFunc(t *testing.T) { for _, tc := range testCases { t.Run(tc.name, func(t *testing.T) { if tc.mustPanic { require.Panics(t, func() { - handleTestCaseFn(t, tc) + handleTestCaseFunc(t, tc) }) } else { require.NotPanics(t, func() { - handleTestCaseFn(t, tc) + handleTestCaseFunc(t, tc) }) } }) @@ -47,7 +47,7 @@ func TestLabelCond(t *testing.T) { require.Equal(t, `test_cond{should="appear",present="/and/\"quoted\""}`, result) } -func BenchmarkBuilderFnTestCases(b *testing.B) { +func BenchmarkBuilderFuncTestCases(b *testing.B) { for _, tc := range testCases { if tc.mustPanic { // Skip test cases that panics as they will break the benchmarks. continue