✨ [collection] Add utilities to serialising maps into comma separated strings (#616)

<!--
Copyright (C) 2020-2022 Arm Limited or its affiliates and Contributors.
All rights reserved.
SPDX-License-Identifier: Apache-2.0
-->
### Description

Added a few utilities to convert maps into slices or strings so that
they can be serialised easily


### Test Coverage

<!--
Please put an `x` in the correct box e.g. `[x]` to indicate the testing
coverage of this change.
-->

- [x]  This change is covered by existing or additional automated tests.
- [ ] Manual testing has been performed (and evidence provided) as
automated testing was not feasible.
- [ ] Additional tests are not required for this change (e.g.
documentation update).

Author: acabarbaye

changes/20250516124618.feature

@@ -0,0 +1 @@
+:sparkles: `[collection]` Add utilities to serialising maps into comma separated strings

utils/collection/parseLists.go

@@ -5,6 +5,7 @@
 package collection
 
 import (
+	"fmt"
 	"strings"
 	"unicode"
 
@@ -73,3 +74,73 @@ func ParseCommaSeparatedListToMap(input string) (pairs map[string]string, err er
 
 	return
 }
+
+// ParseCommaSeparatedListOfPairsToMap returns a map of key value pairs from a string containing a comma separated list of pairs using pairSeparator to separate between keys and values e.g. key1=value1,key2=value2
+func ParseCommaSeparatedListOfPairsToMap(input, pairSeparator string) (pairs map[string]string, err error) {
+	if pairSeparator == "," {
+		pairs, err = ParseCommaSeparatedListToMap(input)
+		return
+	}
+	inputSplit := ParseCommaSeparatedList(input)
+	pairs = make(map[string]string, len(inputSplit))
+	for i := range inputSplit {
+		pair := ParseListWithCleanup(inputSplit[i], pairSeparator)
+		switch len(pair) {
+		case 0:
+			continue
+		case 2:
+			pairs[pair[0]] = pair[1]
+		default:
+			err = commonerrors.Newf(commonerrors.ErrInvalid, "could not parse key value pair '%v'", inputSplit[i])
+			return
+		}
+	}
+	return
+}
+
+// ConvertSliceToCommaSeparatedList converts a slice into a string containing a coma separated list
+func ConvertSliceToCommaSeparatedList[T any](slice []T) string {
+	if len(slice) == 0 {
+		return ""
+	}
+	sliceOfStrings := make([]string, 0, len(slice))
+	for i := range slice {
+		sliceOfStrings = append(sliceOfStrings, fmt.Sprintf("%v", slice[i]))
+	}
+
+	return strings.Join(sliceOfStrings, ",")
+}
+
+// ConvertMapToSlice converts a map to list of keys and values listed sequentially e.g. [key1, value1, key2, value2]
+func ConvertMapToSlice[K comparable, V any](pairs map[K]V) []string {
+	if len(pairs) == 0 {
+		return nil
+	}
+	slice := make([]string, 0, len(pairs)*2)
+	for key, value := range pairs {
+		slice = append(slice, fmt.Sprintf("%v", key), fmt.Sprintf("%v", value))
+	}
+	return slice
+}
+
+// ConvertMapToPairSlice converts a map to list of key value pairs e.g. ["key1=value1", "key2=value2"]
+func ConvertMapToPairSlice[K comparable, V any](pairs map[K]V, pairSeparator string) []string {
+	if len(pairs) == 0 {
+		return nil
+	}
+	slice := make([]string, 0, len(pairs)*2)
+	for key, value := range pairs {
+		slice = append(slice, fmt.Sprintf("%v%v%v", key, pairSeparator, value))
+	}
+	return slice
+}
+
+// ConvertMapToCommaSeparatedList converts a map to a string of comma separated list of keys and values defined sequentially
+func ConvertMapToCommaSeparatedList[K comparable, V any](pairs map[K]V) string {
+	return ConvertSliceToCommaSeparatedList[string](ConvertMapToSlice[K, V](pairs))
+}
+
+// ConvertMapToCommaSeparatedPairsList converts a map to a string of comma separated list of key, value pairs.
+func ConvertMapToCommaSeparatedPairsList[K comparable, V any](pairs map[K]V, pairSeparator string) string {
+	return ConvertSliceToCommaSeparatedList[string](ConvertMapToPairSlice[K, V](pairs, pairSeparator))
+}

utils/collection/parseLists_test.go

@@ -5,14 +5,14 @@
 package collection
 
 import (
+	"maps"
 	"math/rand"
 	"testing"
 	"time"
 
 	"github.com/go-faker/faker/v4"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
-	"golang.org/x/exp/maps"
 
 	"github.com/ARM-software/golang-utils/utils/commonerrors"
 	"github.com/ARM-software/golang-utils/utils/commonerrors/errortest"
@@ -23,47 +23,59 @@ var (
 )
 
 func TestParseCommaSeparatedListWordsOnly(t *testing.T) {
-	stringList := ""
-	stringArray := []string{}
-	// we don't need cryptographically secure random numbers for generating a number of elements in a list
-	lengthOfList := random.Intn(10) //nolint:gosec
-	for i := 0; i < lengthOfList; i++ {
-		word := faker.Word()
-		stringList += word
-		stringArray = append(stringArray, word)
-		numSpacesToAdd := random.Intn(5) //nolint:gosec
-		for j := 0; j < numSpacesToAdd; j++ {
-			stringList += " "
+	t.Run("simple", func(t *testing.T) {
+		stringArray := []string{faker.Word(), faker.Word(), faker.Word(), faker.UUIDDigit(), faker.URL(), faker.Username(), faker.DomainName()}
+		require.Equal(t, stringArray, ParseCommaSeparatedList(ConvertSliceToCommaSeparatedList[string](stringArray)))
+	})
+	t.Run("with whitespaces", func(t *testing.T) {
+		stringList := ""
+		var stringArray []string
+		// we don't need cryptographically secure random numbers for generating a number of elements in a list
+		lengthOfList := random.Intn(10) //nolint:gosec
+		for i := 0; i < lengthOfList; i++ {
+			word := faker.Word()
+			stringList += word
+			stringArray = append(stringArray, word)
+			numSpacesToAdd := random.Intn(5) //nolint:gosec
+			for j := 0; j < numSpacesToAdd; j++ {
+				stringList += " "
+			}
+			stringList += ","
 		}
-		stringList += ","
-	}
-	finalList := ParseCommaSeparatedList(stringList)
-	require.Equal(t, stringArray, finalList)
+		finalList := ParseCommaSeparatedList(stringList)
+		require.Equal(t, stringArray, finalList)
+	})
 }
 
 // Test to make sure that spaces that show up within the words aren't removed
 func TestParseCommaSeparatedListWithSpacesBetweenWords(t *testing.T) {
-	stringList := ""
-	stringArray := []string{}
-	// we don't need cryptographically secure random numbers for generating a number of elements in a list
-	lengthOfList := random.Intn(10) //nolint:gosec
-	for i := 0; i < lengthOfList; i++ {
-		word := faker.Sentence()
-		stringList += word
-		stringArray = append(stringArray, word)
-		numSpacesToAdd := random.Intn(5) //nolint:gosec
-		for j := 0; j < numSpacesToAdd; j++ {
-			stringList += " "
+	t.Run("simple", func(t *testing.T) {
+		stringArray := []string{faker.Paragraph(), faker.Word(), faker.Sentence(), faker.UUIDDigit(), faker.Name(), faker.Username(), faker.DomainName()}
+		require.Equal(t, stringArray, ParseCommaSeparatedList(ConvertSliceToCommaSeparatedList[string](stringArray)))
+	})
+	t.Run("with whitespaces", func(t *testing.T) {
+		stringList := ""
+		var stringArray []string
+		// we don't need cryptographically secure random numbers for generating a number of elements in a list
+		lengthOfList := random.Intn(10) //nolint:gosec
+		for i := 0; i < lengthOfList; i++ {
+			word := faker.Sentence()
+			stringList += word
+			stringArray = append(stringArray, word)
+			numSpacesToAdd := random.Intn(5) //nolint:gosec
+			for j := 0; j < numSpacesToAdd; j++ {
+				stringList += " "
+			}
+			stringList += ","
 		}
-		stringList += ","
-	}
-	finalList := ParseCommaSeparatedList(stringList)
-	require.Equal(t, stringArray, finalList)
+		finalList := ParseCommaSeparatedList(stringList)
+		require.Equal(t, stringArray, finalList)
+	})
 }
 
 func TestParseCommaSeparatedListWithSpacesBetweenWordsKeepBlanks(t *testing.T) {
 	stringList := ""
-	stringArray := []string{}
+	var stringArray []string
 	// we don't need cryptographically secure random numbers for generating a number of elements in a list
 	lengthOfList := random.Intn(10) + 8 //nolint:gosec
 	for i := 0; i < lengthOfList; i++ {
@@ -94,6 +106,17 @@ func TestParseCommaSeparatedListWithSpacesBetweenWordsKeepBlanks(t *testing.T) {
 }
 
 func TestParseCommaSeparatedListToMap(t *testing.T) {
+	randomMap := map[string]string{
+		faker.Sentence(): faker.Sentence(),
+		faker.Word():     faker.Paragraph(),
+		faker.Name():     faker.Sentence(),
+		faker.Sentence(): faker.Sentence(),
+		faker.Word():     faker.Paragraph(),
+		faker.Name():     faker.Sentence(),
+		faker.Sentence(): faker.Sentence(),
+		faker.Word():     faker.Paragraph(),
+		faker.Name():     faker.Sentence(),
+	}
 	for _, test := range []struct {
 		Name     string
 		Input    string
@@ -111,6 +134,7 @@ func TestParseCommaSeparatedListToMap(t *testing.T) {
 		{"Normal 8", ",", map[string]string{}, nil},
 		{"Normal 9", ",,,,,", map[string]string{}, nil},
 		{"Normal 10", ",, ,,  ,", map[string]string{}, nil},
+		{"Normal 11", ConvertMapToCommaSeparatedList[string, string](randomMap), randomMap, nil},
 		{"Bad 1", "one", nil, commonerrors.ErrInvalid},
 		{"Bad 1", "one, two, three", nil, commonerrors.ErrInvalid},
 		{"Bad 2", "one element with spaces", nil, commonerrors.ErrInvalid},
@@ -125,3 +149,51 @@ func TestParseCommaSeparatedListToMap(t *testing.T) {
 		})
 	}
 }
+
+func TestParseCommaSeparatedPairListToMap(t *testing.T) {
+	randomMap := map[string]string{
+		faker.Sentence(): faker.Sentence(),
+		faker.Word():     faker.Paragraph(),
+		faker.Name():     faker.Sentence(),
+		faker.Sentence(): faker.Sentence(),
+		faker.Word():     faker.Paragraph(),
+		faker.Name():     faker.Sentence(),
+		faker.Sentence(): faker.Sentence(),
+		faker.Word():     faker.Paragraph(),
+		faker.Name():     faker.Sentence(),
+	}
+	for _, test := range []struct {
+		Name          string
+		Input         string
+		Expected      map[string]string
+		Err           error
+		PairSeparator string
+	}{
+		{"Normal 1", "hello=world", map[string]string{"hello": "world"}, nil, "="},
+		{"Normal 2", "hello+world,adrien+cabarbaye", map[string]string{"hello": "world", "adrien": "cabarbaye"}, nil, "+"},
+		{"Normal 2", "hello, world, adrien, cabarbaye", map[string]string{"hello": "world", "adrien": "cabarbaye"}, nil, ","},
+		{"Normal 2.5", "hello= world, adrien = cabarbaye", map[string]string{"hello": "world", "adrien": "cabarbaye"}, nil, "="},
+		{"Normal 3", "hello&world,adrien&cabarbaye,", map[string]string{"hello": "world", "adrien": "cabarbaye"}, nil, "&"},
+		{"Normal 4", "hello%%world,,,,adrien%%cabarbaye,,,", map[string]string{"hello": "world", "adrien": "cabarbaye"}, nil, "%%"},
+		{"Normal 5", "hello$$$world,this$$$value has spaces", map[string]string{"hello": "world", "this": "value has spaces"}, nil, "$$$"},
+		{"Normal 6", "hello__world,,,this__value has spaces,,,", map[string]string{"hello": "world", "this": "value has spaces"}, nil, "__"},
+		{"Normal 7", "", map[string]string{}, nil, "+"},
+		{"Normal 8", ",", map[string]string{}, nil, "+"},
+		{"Normal 9", ",,,,,", map[string]string{}, nil, "^"},
+		{"Normal 10", ",, ,,  ,", map[string]string{}, nil, "+"},
+		{"Normal 11", ConvertMapToCommaSeparatedPairsList[string, string](randomMap, "/"), randomMap, nil, "/"},
+		{"Normal 12", ConvertMapToCommaSeparatedPairsList[string, string](randomMap, "  "), randomMap, nil, "  "},
+		{"Bad 1", "one", nil, commonerrors.ErrInvalid, "+"},
+		{"Bad 1", "one, two, three", nil, commonerrors.ErrInvalid, "+"},
+		{"Bad 2", "one element with spaces", nil, commonerrors.ErrInvalid, "+"},
+		{"Bad 3", "one element with spaces and end comma,", nil, commonerrors.ErrInvalid, "+"},
+		{"Bad 4", "one element with spaces and multiple end commas,,,", nil, commonerrors.ErrInvalid, "+"},
+		{"Bad 5", ",,,one element with spaces and multiple end/beginning commas,,,", nil, commonerrors.ErrInvalid, "="},
+	} {
+		t.Run(test.Name, func(t *testing.T) {
+			pairs, err := ParseCommaSeparatedListOfPairsToMap(test.Input, test.PairSeparator)
+			errortest.AssertError(t, err, test.Err)
+			assert.True(t, maps.Equal(test.Expected, pairs))
+		})
+	}
+}