Add rcutils_join function for concatenating strings (ros2#490)

This function complements the rcutils_split function. It joins an array
of string tokens together with the given separator inserted between each
token.

Signed-off-by: Scott K Logan <logans@cottsay.net>

Author: cottsay

CMakeLists.txt

@@ -75,6 +75,7 @@ set(rcutils_sources
   src/find.c
   src/format_string.c
   src/hash_map.c
+  src/join.c
   src/logging.c
   src/process.c
   src/qsort.c
@@ -302,6 +303,13 @@ if(BUILD_TESTING)
     target_link_libraries(test_split ${PROJECT_NAME})
   endif()
 
+  ament_add_gtest(test_join
+    test/test_join.cpp
+  )
+  if(TARGET test_join)
+    target_link_libraries(test_join ${PROJECT_NAME})
+  endif()
+
   ament_add_gtest(test_find
     test/test_find.cpp
   )

include/rcutils/join.h

@@ -0,0 +1,48 @@
+// Copyright 2025 Open Source Robotics Foundation, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/// \file
+
+#ifndef RCUTILS__JOIN_H_
+#define RCUTILS__JOIN_H_
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+#include "rcutils/allocator.h"
+#include "rcutils/types.h"
+#include "rcutils/visibility_control.h"
+
+/// Concatenate members of an array into a single string
+/**
+ * \param[in] string_array with the tokens to concatenate
+ * \param[in] separator string to be inserted between tokens
+ * \param[in] allocator for allocating new memory for the output string
+ * \return concatenated string, or
+ * \return `NULL` if there is an error.
+ */
+RCUTILS_PUBLIC
+char *
+rcutils_join(
+  const rcutils_string_array_t * string_array,
+  const char * separator,
+  rcutils_allocator_t allocator);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif  // RCUTILS__JOIN_H_

src/join.c

@@ -0,0 +1,80 @@
+// Copyright 2025 Open Source Robotics Foundation, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+#include <string.h>
+
+#include "rcutils/error_handling.h"
+#include "rcutils/join.h"
+#include "rcutils/macros.h"
+#include "rcutils/strdup.h"
+#include "rcutils/types.h"
+
+char *
+rcutils_join(
+  const rcutils_string_array_t * string_array,
+  const char * separator,
+  rcutils_allocator_t allocator)
+{
+  RCUTILS_CAN_RETURN_WITH_ERROR_OF(NULL);
+
+  RCUTILS_CHECK_ARGUMENT_FOR_NULL(string_array, NULL);
+  RCUTILS_CHECK_ARGUMENT_FOR_NULL(separator, NULL);
+  RCUTILS_CHECK_ALLOCATOR_WITH_MSG(
+    &allocator, "allocator is invalid", return NULL);
+
+  if (string_array->size < 1) {
+    return rcutils_strdup("", allocator);
+  }
+
+  size_t sep_length = strlen(separator);
+  size_t string_length = sep_length * (string_array->size - 1);
+
+  for (size_t i = 0; i < string_array->size; i++) {
+    if (string_array->data[i]) {
+      string_length += strlen(string_array->data[i]);
+    }
+  }
+
+  char * new_string = allocator.allocate(string_length + 1, allocator.state);
+  if (NULL == new_string) {
+    RCUTILS_SET_ERROR_MSG("failed to allocate memory for new string");
+    return NULL;
+  }
+
+  char * pos = new_string;
+  for (size_t i = 0; i < string_array->size; i++) {
+    if (i != 0) {
+      memcpy(pos, separator, sep_length);
+      pos += sep_length;
+    }
+    if (string_array->data[i]) {
+      string_length = strlen(string_array->data[i]);
+      memcpy(pos, string_array->data[i], string_length);
+      pos += string_length;
+    }
+  }
+
+  *pos = '\0';
+
+  return new_string;
+}
+
+#ifdef __cplusplus
+}
+#endif

test/test_join.cpp

@@ -0,0 +1,92 @@
+// Copyright 2025 Open Source Robotics Foundation, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include "gtest/gtest.h"
+
+#include "./allocator_testing_utils.h"
+#include "./time_bomb_allocator_testing_utils.h"
+#include "rcutils/error_handling.h"
+#include "rcutils/join.h"
+#include "rcutils/types/string_array.h"
+
+#define LOG(expected, actual) printf("Expected: %s Actual: %s\n", expected, actual);
+
+TEST(test_join, join) {
+  rcutils_allocator_t allocator = rcutils_get_default_allocator();
+  rcutils_allocator_t bad_allocator = rcutils_get_zero_initialized_allocator();
+  rcutils_allocator_t time_bomb_allocator = get_time_bomb_allocator();
+  rcutils_string_array_t tokens0 = rcutils_get_zero_initialized_string_array();
+  rcutils_string_array_t tokens1 = rcutils_get_zero_initialized_string_array();
+  rcutils_string_array_t tokens2 = rcutils_get_zero_initialized_string_array();
+  char * new_string;
+
+  ASSERT_EQ(
+    RCUTILS_RET_OK,
+    rcutils_string_array_init(&tokens0, 0, &allocator));
+  ASSERT_EQ(
+    RCUTILS_RET_OK,
+    rcutils_string_array_init(&tokens1, 1, &allocator));
+  tokens1.data[0] = strdup("hallo");
+  ASSERT_EQ(
+    RCUTILS_RET_OK,
+    rcutils_string_array_init(&tokens2, 2, &allocator));
+  tokens2.data[0] = strdup("hello");
+  tokens2.data[1] = strdup("world");
+
+  EXPECT_STREQ(
+    nullptr,
+    rcutils_join(NULL, "-", allocator));
+  rcutils_reset_error();
+
+  EXPECT_STREQ(
+    nullptr,
+    rcutils_join(&tokens0, NULL, allocator));
+  rcutils_reset_error();
+
+  EXPECT_STREQ(
+    nullptr,
+    rcutils_join(&tokens0, " ", bad_allocator));
+  rcutils_reset_error();
+
+  // Allocating new_string fails
+  set_time_bomb_allocator_malloc_count(time_bomb_allocator, 0);
+  EXPECT_STREQ(
+    nullptr,
+    rcutils_join(&tokens2, " ", time_bomb_allocator));
+  rcutils_reset_error();
+
+  new_string = rcutils_join(&tokens0, " ", allocator);
+  EXPECT_STREQ("", new_string);
+  allocator.deallocate(new_string, &allocator.state);
+
+  new_string = rcutils_join(&tokens1, " ", allocator);
+  EXPECT_STREQ("hallo", new_string);
+  allocator.deallocate(new_string, &allocator.state);
+
+  new_string = rcutils_join(&tokens2, "", allocator);
+  EXPECT_STREQ("helloworld", new_string);
+  allocator.deallocate(new_string, &allocator.state);
+
+  new_string = rcutils_join(&tokens2, " ", allocator);
+  EXPECT_STREQ("hello world", new_string);
+  allocator.deallocate(new_string, &allocator.state);
+
+  new_string = rcutils_join(&tokens2, " ... ", allocator);
+  EXPECT_STREQ("hello ... world", new_string);
+  allocator.deallocate(new_string, &allocator.state);
+
+  EXPECT_EQ(
+    RCUTILS_RET_OK,
+    rcutils_string_array_fini(&tokens0));
+}