Add a stub for `createNestedArray()`

extras/tests/Deprecated/CMakeLists.txt

@@ -16,6 +16,7 @@ endif()
 
 add_executable(DeprecatedTests
 	add.cpp
+	createNestedArray.cpp
 	BasicJsonDocument.cpp
 	DynamicJsonDocument.cpp
 	memoryUsage.cpp

extras/tests/Deprecated/createNestedArray.cpp

@@ -0,0 +1,111 @@
+// ArduinoJson - https://arduinojson.org
+// Copyright © 2014-2023, Benoit BLANCHON
+// MIT License
+
+#include <ArduinoJson.h>
+#include <catch.hpp>
+
+#include <string>
+
+TEST_CASE("JsonDocument::createNestedArray()") {
+  JsonDocument doc;
+
+  SECTION("createNestedArray()") {
+    JsonArray array = doc.createNestedArray();
+    array.add(42);
+    REQUIRE(doc.as<std::string>() == "[[42]]");
+  }
+
+  SECTION("createNestedArray(const char*)") {
+    JsonArray array = doc.createNestedArray("key");
+    array.add(42);
+    REQUIRE(doc.as<std::string>() == "{\"key\":[42]}");
+  }
+
+  SECTION("createNestedArray(std::string)") {
+    JsonArray array = doc.createNestedArray(std::string("key"));
+    array.add(42);
+    REQUIRE(doc.as<std::string>() == "{\"key\":[42]}");
+  }
+
+#ifdef HAS_VARIABLE_LENGTH_ARRAY
+  SECTION("createNestedArray(VLA)") {
+    size_t i = 16;
+    char vla[i];
+    strcpy(vla, "key");
+    JsonArray array = doc.createNestedArray(vla);
+    array.add(42);
+    REQUIRE(doc.as<std::string>() == "{\"key\":[42]}");
+  }
+#endif
+}
+
+TEST_CASE("JsonArray::createNestedArray()") {
+  JsonDocument doc;
+  JsonArray array = doc.to<JsonArray>();
+  JsonArray nestedArray = array.createNestedArray();
+  nestedArray.add(42);
+  REQUIRE(doc.as<std::string>() == "[[42]]");
+}
+
+TEST_CASE("JsonObject::createNestedArray()") {
+  JsonDocument doc;
+  JsonObject object = doc.to<JsonObject>();
+
+  SECTION("createNestedArray(const char*)") {
+    JsonArray array = object.createNestedArray("key");
+    array.add(42);
+    REQUIRE(doc.as<std::string>() == "{\"key\":[42]}");
+  }
+
+  SECTION("createNestedArray(std::string)") {
+    JsonArray array = object.createNestedArray(std::string("key"));
+    array.add(42);
+    REQUIRE(doc.as<std::string>() == "{\"key\":[42]}");
+  }
+
+#ifdef HAS_VARIABLE_LENGTH_ARRAY
+  SECTION("createNestedArray(VLA)") {
+    size_t i = 16;
+    char vla[i];
+    strcpy(vla, "key");
+    JsonArray array = object.createNestedArray(vla);
+    array.add(42);
+    REQUIRE(doc.as<std::string>() == "{\"key\":[42]}");
+  }
+#endif
+}
+
+TEST_CASE("JsonVariant::createNestedArray()") {
+  JsonDocument doc;
+  JsonVariant variant = doc.to<JsonVariant>();
+
+  SECTION("createNestedArray()") {
+    JsonArray array = variant.createNestedArray();
+    array.add(42);
+    REQUIRE(doc.as<std::string>() == "[[42]]");
+  }
+
+  SECTION("createNestedArray(const char*)") {
+    JsonArray array = variant.createNestedArray("key");
+    array.add(42);
+    REQUIRE(doc.as<std::string>() == "{\"key\":[42]}");
+  }
+
+  SECTION("createNestedArray(std::string)") {
+    JsonArray array = variant.createNestedArray(std::string("key"));
+    array.add(42);
+    REQUIRE(doc.as<std::string>() == "{\"key\":[42]}");
+  }
+
+#ifdef HAS_VARIABLE_LENGTH_ARRAY
+  SECTION("createNestedArray(VLA)") {
+    size_t i = 16;
+    char vla[i];
+    strcpy(vla, "key");
+    JsonArray array = variant.createNestedArray(vla);
+    array.add(42);
+    REQUIRE(doc.as<std::string>() == "{\"key\":[42]}");
+  }
+#endif
+}

src/ArduinoJson/Array/JsonArray.hpp

@@ -164,6 +164,12 @@ class JsonArray : public detail::VariantOperators<JsonArray> {
     return add<JsonVariant>();
   }
 
+  // DEPRECATED: use add<JsonArray>() instead
+  ARDUINOJSON_DEPRECATED("use add<JsonArray>() instead")
+  JsonArray createNestedArray() const {
+    return add<JsonArray>();
+  }
+
   // DEPRECATED: always returns zero
   ARDUINOJSON_DEPRECATED("always returns zero")
   size_t memoryUsage() const {

src/ArduinoJson/Document/JsonDocument.hpp

@@ -297,6 +297,26 @@ class JsonDocument : public detail::VariantOperators<const JsonDocument&> {
     return add<JsonVariant>();
   }
 
+  // DEPRECATED: use add<JsonArray>() instead
+  ARDUINOJSON_DEPRECATED("use add<JsonArray>() instead")
+  JsonArray createNestedArray() {
+    return add<JsonArray>();
+  }
+
+  // DEPRECATED: use doc[key].to<JsonArray>() instead
+  template <typename TChar>
+  ARDUINOJSON_DEPRECATED("use doc[key].to<JsonArray>() instead")
+  JsonArray createNestedArray(TChar* key) {
+    return operator[](key).template to<JsonArray>();
+  }
+
+  // DEPRECATED: use doc[key].to<JsonArray>() instead
+  template <typename TString>
+  ARDUINOJSON_DEPRECATED("use doc[key].to<JsonArray>() instead")
+  JsonArray createNestedArray(const TString& key) {
+    return operator[](key).template to<JsonArray>();
+  }
+
   // DEPRECATED: always returns zero
   ARDUINOJSON_DEPRECATED("always returns zero")
   size_t memoryUsage() const {

src/ArduinoJson/Object/JsonObject.hpp

@@ -166,6 +166,20 @@ class JsonObject : public detail::VariantOperators<JsonObject> {
                                          resources_) != 0;
   }
 
+  // DEPRECATED: use obj[key].to<JsonArray>() instead
+  template <typename TChar>
+  ARDUINOJSON_DEPRECATED("use obj[key].to<JsonArray>() instead")
+  JsonArray createNestedArray(TChar* key) const {
+    return operator[](key).template to<JsonArray>();
+  }
+
+  // DEPRECATED: use obj[key].to<JsonArray>() instead
+  template <typename TString>
+  ARDUINOJSON_DEPRECATED("use obj[key].to<JsonArray>() instead")
+  JsonArray createNestedArray(const TString& key) const {
+    return operator[](key).template to<JsonArray>();
+  }
+
   // DEPRECATED: always returns zero
   ARDUINOJSON_DEPRECATED("always returns zero")
   size_t memoryUsage() const {

src/ArduinoJson/Variant/VariantRefBase.hpp

@@ -225,6 +225,20 @@ class VariantRefBase : public VariantTag {
   ARDUINOJSON_DEPRECATED("use add<JsonVariant>() instead")
   JsonVariant add() const;
 
+  // DEPRECATED: use add<JsonArray>() instead
+  ARDUINOJSON_DEPRECATED("use add<JsonArray>() instead")
+  JsonArray createNestedArray() const;
+
+  // DEPRECATED: use var[key].to<JsonArray>() instead
+  template <typename TChar>
+  ARDUINOJSON_DEPRECATED("use var[key].to<JsonArray>() instead")
+  JsonArray createNestedArray(TChar* key) const;
+
+  // DEPRECATED: use var[key].to<JsonArray>() instead
+  template <typename TString>
+  ARDUINOJSON_DEPRECATED("use var[key].to<JsonArray>() instead")
+  JsonArray createNestedArray(const TString& key) const;
+
   // DEPRECATED: always returns zero
   ARDUINOJSON_DEPRECATED("always returns zero")
   size_t memoryUsage() const {

src/ArduinoJson/Variant/VariantRefBaseImpl.hpp

@@ -15,6 +15,24 @@ inline JsonVariant VariantRefBase<TDerived>::add() const {
   return add<JsonVariant>();
 }
 
+template <typename TDerived>
+inline JsonArray VariantRefBase<TDerived>::createNestedArray() const {
+  return add<JsonArray>();
+}
+
+template <typename TDerived>
+template <typename TChar>
+inline JsonArray VariantRefBase<TDerived>::createNestedArray(TChar* key) const {
+  return operator[](key).template to<JsonArray>();
+}
+
+template <typename TDerived>
+template <typename TString>
+inline JsonArray VariantRefBase<TDerived>::createNestedArray(
+    const TString& key) const {
+  return operator[](key).template to<JsonArray>();
+}
+
 template <typename TDerived>
 inline void convertToJson(const VariantRefBase<TDerived>& src,
                           JsonVariant dst) {