Add pcommon.Map helper to add a key to the map if does not exists (#14023)

This new API is intended to be similar with "LoadOrStore" from the
`sync.Map` and a helper to avoid iterating over the map (lookup) twice
for when we need to only insert a key if it does not exists.

Example
https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/internal/coreinternal/attraction/attraction.go#L307:
```
if _, found = attrs.Get(action.Key); found {
	continue
}
av.CopyTo(attrs.PutEmpty(action.Key))
```

We lookup key in `Get` as well as `PutEmpty`, and this can be re-written
as:

```
if val, found = attrs.GetOrPutEmpty(action.Key); !found {
	av.CopyTo(val)
}
```

Signed-off-by: Bogdan Drutu <[email protected]>

Author: bogdandrutu

.chloggen/get-or-put-empty.yaml

@@ -0,0 +1,25 @@
+# Use this changelog template to create an entry for release notes.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the component, or a single word describing the area of concern, (e.g. otlpreceiver)
+component: pkg/pdata
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add pcommon.Map helper to add a key to the map if does not exists
+
+# One or more tracking issues or pull requests related to the change
+issues: [14023]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:
+
+# Optional: The change log or logs in which this entry should be included.
+# e.g. '[user]' or '[user, api]'
+# Include 'user' if the change is relevant to end users.
+# Include 'api' if there is a change to a library API.
+# Default: '[user]'
+change_logs: [api]

pdata/pcommon/map.go

@@ -121,6 +121,18 @@ func (m Map) PutEmpty(k string) Value {
 	return newValue(&(*m.getOrig())[len(*m.getOrig())-1].Value, m.getState())
 }
 
+// GetOrPutEmpty returns the Value associated with the key and true (loaded) if the key exists in the map,
+// otherwise inserts an empty value to the map under the given key and returns the inserted value
+// and false (loaded).
+func (m Map) GetOrPutEmpty(k string) (Value, bool) {
+	m.getState().AssertMutable()
+	if av, existing := m.Get(k); existing {
+		return av, true
+	}
+	*m.getOrig() = append(*m.getOrig(), otlpcommon.KeyValue{Key: k})
+	return newValue(&(*m.getOrig())[len(*m.getOrig())-1].Value, m.getState()), false
+}
+
 // PutStr performs the Insert or Update action. The Value is
 // inserted to the map that did not originally have the key. The key/value is
 // updated to the map where the key already existed.

pdata/pcommon/map_test.go

@@ -76,6 +76,8 @@ func TestMapReadOnly(t *testing.T) {
 	assert.Panics(t, func() { m.PutInt("k2", 123) })
 	assert.Panics(t, func() { m.PutDouble("k2", 1.23) })
 	assert.Panics(t, func() { m.PutBool("k2", true) })
+	assert.Panics(t, func() { m.PutEmpty("foo") })
+	assert.Panics(t, func() { m.GetOrPutEmpty("foo") })
 	assert.Panics(t, func() { m.PutEmptyBytes("k2") })
 	assert.Panics(t, func() { m.PutEmptyMap("k2") })
 	assert.Panics(t, func() { m.PutEmptySlice("k2") })
@@ -111,6 +113,24 @@ func TestMapPutEmpty(t *testing.T) {
 	assert.Equal(t, int64(1), v2.Int())
 }
 
+func TestMapGetOrPutEmpty(t *testing.T) {
+	m := NewMap()
+	v := m.PutEmpty("k1")
+	v.SetStr("test")
+	assert.Equal(t, map[string]any{
+		"k1": "test",
+	}, m.AsRaw())
+
+	v, found := m.GetOrPutEmpty("k1")
+	assert.True(t, found)
+	require.Equal(t, ValueTypeStr, v.Type())
+	assert.Equal(t, "test", v.Str())
+
+	v, found = m.GetOrPutEmpty("k2")
+	assert.False(t, found)
+	require.Equal(t, ValueTypeEmpty, v.Type())
+}
+
 func TestMapPutEmptyMap(t *testing.T) {
 	m := NewMap()
 	childMap := m.PutEmptyMap("k1")
@@ -607,6 +627,7 @@ func TestInvalidMap(t *testing.T) {
 	assert.Panics(t, func() { v.Remove("foo") })
 	assert.Panics(t, func() { v.RemoveIf(testFunc) })
 	assert.Panics(t, func() { v.PutEmpty("foo") })
+	assert.Panics(t, func() { v.GetOrPutEmpty("foo") })
 	assert.Panics(t, func() { v.PutStr("foo", "bar") })
 	assert.Panics(t, func() { v.PutInt("foo", 1) })
 	assert.Panics(t, func() { v.PutDouble("foo", 1.1) })