Added `deprecated` attribute on `asArray()`, `asObject()` and `asString()` (issue #420)

CHANGELOG.md

@@ -10,6 +10,7 @@ HEAD
 * Fixed error when the key of a `JsonObject` is a `char[]` (issue #423)
 * Reduced code size when using `const` references
 * Fixed error with string of type `unsigned char*` (issue #428)
+* Added `deprecated` attribute on `asArray()`, `asObject()` and `asString()` (issue #420)
 
 v5.8.1
 ------

include/ArduinoJson/Configuration.hpp

@@ -7,6 +7,11 @@
 
 #pragma once
 
+// enable deprecated functions by default
+#ifndef ARDUINOJSON_ENABLE_DEPRECATED
+#define ARDUINOJSON_ENABLE_DEPRECATED 1
+#endif
+
 #ifdef ARDUINO  // assume this is an embedded platform
 
 // store using float instead of double to reduce the memory usage (issue #134)

include/ArduinoJson/JsonArray.hpp

@@ -193,7 +193,7 @@ class JsonArray : public Internals::JsonPrintable<JsonArray>,
   void copyTo(T (&array)[N1][N2]) const {
     size_t i = 0;
     for (const_iterator it = begin(); it != end() && i < N1; ++it) {
-      it->asArray().copyTo(array[i++]);
+      it->as<JsonArray>().copyTo(array[i++]);
     }
   }
 

include/ArduinoJson/JsonArraySubscript.hpp

@@ -107,13 +107,13 @@ inline const JsonArraySubscript JsonArray::operator[](size_t index) const {
 
 template <typename TImplem>
 inline JsonArraySubscript JsonVariantBase<TImplem>::operator[](int index) {
-  return asArray()[index];
+  return as<JsonArray>()[index];
 }
 
 template <typename TImplem>
 inline const JsonArraySubscript JsonVariantBase<TImplem>::operator[](
     int index) const {
-  return asArray()[index];
+  return as<JsonArray>()[index];
 }
 
 }  // namespace ArduinoJson

include/ArduinoJson/JsonVariant.hpp

@@ -136,7 +136,7 @@ class JsonVariant : public JsonVariantBase<JsonVariant> {
   const typename TypeTraits::EnableIf<TypeTraits::IsSignedIntegral<T>::value,
                                       T>::type
   as() const {
-    return static_cast<T>(asInteger());
+    return static_cast<T>(variantAsInteger());
   }
   //
   // short as<unsigned short>() const;
@@ -155,7 +155,7 @@ class JsonVariant : public JsonVariantBase<JsonVariant> {
   const typename TypeTraits::EnableIf<TypeTraits::IsFloatingPoint<T>::value,
                                       T>::type
   as() const {
-    return static_cast<T>(asFloat());
+    return static_cast<T>(variantAsFloat());
   }
   //
   // const char* as<const char*>() const;
@@ -165,7 +165,7 @@ class JsonVariant : public JsonVariantBase<JsonVariant> {
                                     TypeTraits::IsSame<T, char *>::value,
                                 const char *>::type
   as() const {
-    return asString();
+    return variantAsString();
   }
   //
   // std::string as<std::string>() const;
@@ -173,7 +173,7 @@ class JsonVariant : public JsonVariantBase<JsonVariant> {
   template <typename T>
   typename TypeTraits::EnableIf<Internals::StringTraits<T>::has_append, T>::type
   as() const {
-    const char *cstr = asString();
+    const char *cstr = variantAsString();
     if (cstr) return T(cstr);
     T s;
     printTo(s);
@@ -185,7 +185,7 @@ class JsonVariant : public JsonVariantBase<JsonVariant> {
   const typename TypeTraits::EnableIf<TypeTraits::IsSame<T, bool>::value,
                                       T>::type
   as() const {
-    return asInteger() != 0;
+    return variantAsInteger() != 0;
   }
   //
   // JsonArray& as<JsonArray> const;
@@ -196,7 +196,7 @@ class JsonVariant : public JsonVariantBase<JsonVariant> {
                          JsonArray>::value,
       JsonArray &>::type
   as() const {
-    return asArray();
+    return variantAsArray();
   }
   //
   // const JsonArray& as<const JsonArray&> const;
@@ -206,7 +206,7 @@ class JsonVariant : public JsonVariantBase<JsonVariant> {
                          const JsonArray>::value,
       const JsonArray &>::type
   as() const {
-    return asArray();
+    return variantAsArray();
   }
   //
   // JsonObject& as<JsonObject> const;
@@ -217,7 +217,7 @@ class JsonVariant : public JsonVariantBase<JsonVariant> {
                          JsonObject>::value,
       JsonObject &>::type
   as() const {
-    return asObject();
+    return variantAsObject();
   }
   //
   // JsonObject& as<const JsonObject> const;
@@ -228,7 +228,7 @@ class JsonVariant : public JsonVariantBase<JsonVariant> {
                          const JsonObject>::value,
       const JsonObject &>::type
   as() const {
-    return asObject();
+    return variantAsObject();
   }
   //
   // JsonVariant as<JsonVariant> const;
@@ -313,23 +313,17 @@ class JsonVariant : public JsonVariantBase<JsonVariant> {
     return _type != Internals::JSON_UNDEFINED;
   }
 
-  // DEPRECATED: use as<char*>() instead
-  const char *asString() const;
-
-  // DEPRECATED: use as<JsonArray>() instead
-  JsonArray &asArray() const;
-
-  // DEPRECATED: use as<JsonObject>() instead
-  JsonObject &asObject() const;
-
  private:
   // It's not allowed to store a char
   template <typename T>
   JsonVariant(T value, typename TypeTraits::EnableIf<
                            TypeTraits::IsSame<T, char>::value>::type * = 0);
 
-  Internals::JsonFloat asFloat() const;
-  Internals::JsonInteger asInteger() const;
+  JsonArray &variantAsArray() const;
+  JsonObject &variantAsObject() const;
+  const char *variantAsString() const;
+  Internals::JsonFloat variantAsFloat() const;
+  Internals::JsonInteger variantAsInteger() const;
   Internals::JsonUInt asUnsignedInteger() const;
   bool isBoolean() const;
   bool isFloat() const;

include/ArduinoJson/JsonVariantBase.hpp

@@ -21,10 +21,22 @@ class JsonObjectSubscript;
 template <typename TImpl>
 class JsonVariantBase : public Internals::JsonPrintable<TImpl> {
  public:
-  // DEPRECATED: use as<char*>() instead
+#if ARDUINOJSON_ENABLE_DEPRECATED
+  DEPRECATED("use as<JsonArray>() instead")
+  FORCE_INLINE JsonArray &asArray() const {
+    return as<JsonArray>();
+  }
+
+  DEPRECATED("use as<JsonObject>() instead")
+  FORCE_INLINE JsonObject &asObject() const {
+    return as<JsonObject>();
+  }
+
+  DEPRECATED("use as<char*>() instead")
   FORCE_INLINE const char *asString() const {
     return as<const char *>();
   }
+#endif
 
   // Gets the variant as an array.
   // Returns a reference to the JsonArray or JsonArray::invalid() if the
@@ -34,11 +46,6 @@ class JsonVariantBase : public Internals::JsonPrintable<TImpl> {
     return as<JsonArray &>();
   }
 
-  // DEPRECATED: use as<JsonArray>() instead
-  FORCE_INLINE JsonArray &asArray() const {
-    return as<JsonArray &>();
-  }
-
   // Gets the variant as an object.
   // Returns a reference to the JsonObject or JsonObject::invalid() if the
   // variant is not an object.
@@ -46,11 +53,6 @@ class JsonVariantBase : public Internals::JsonPrintable<TImpl> {
     return as<JsonObject &>();
   }
 
-  // DEPRECATED: use as<JsonObject>() instead
-  FORCE_INLINE JsonObject &asObject() const {
-    return as<JsonObject &>();
-  }
-
   template <typename T>
   FORCE_INLINE operator T() const {
     return as<T>();
@@ -65,7 +67,7 @@ class JsonVariantBase : public Internals::JsonPrintable<TImpl> {
   // Returns the size of the array or object if the variant has that type.
   // Returns 0 if the variant is neither an array nor an object
   size_t size() const {
-    return asArray().size() + asObject().size();
+    return as<JsonArray>().size() + as<JsonObject>().size();
   }
 
   // Mimics an array.
@@ -86,7 +88,7 @@ class JsonVariantBase : public Internals::JsonPrintable<TImpl> {
       Internals::StringTraits<TString>::has_equals,
       const JsonObjectSubscript<const TString &> >::type
   operator[](const TString &key) const {
-    return asObject()[key];
+    return as<JsonObject>()[key];
   }
   //
   // const JsonObjectSubscript operator[](TKey) const;
@@ -96,7 +98,7 @@ class JsonVariantBase : public Internals::JsonPrintable<TImpl> {
       Internals::StringTraits<TString>::has_equals,
       JsonObjectSubscript<const TString &> >::type
   operator[](const TString &key) {
-    return asObject()[key];
+    return as<JsonObject>()[key];
   }
   //
   // JsonObjectSubscript operator[](TKey);
@@ -106,7 +108,7 @@ class JsonVariantBase : public Internals::JsonPrintable<TImpl> {
       Internals::StringTraits<TString *>::has_equals,
       JsonObjectSubscript<const TString *> >::type
   operator[](const TString *key) {
-    return asObject()[key];
+    return as<JsonObject>()[key];
   }
   //
   // JsonObjectSubscript operator[](TKey);
@@ -116,7 +118,7 @@ class JsonVariantBase : public Internals::JsonPrintable<TImpl> {
       Internals::StringTraits<TString *>::has_equals,
       const JsonObjectSubscript<const TString *> >::type
   operator[](const TString *key) const {
-    return asObject()[key];
+    return as<JsonObject>()[key];
   }
 
  private:

include/ArduinoJson/JsonVariantImpl.hpp

@@ -37,17 +37,17 @@ inline JsonVariant::JsonVariant(const JsonObject &object) {
   }
 }
 
-inline JsonArray &JsonVariant::asArray() const {
+inline JsonArray &JsonVariant::variantAsArray() const {
   if (_type == Internals::JSON_ARRAY) return *_content.asArray;
   return JsonArray::invalid();
 }
 
-inline JsonObject &JsonVariant::asObject() const {
+inline JsonObject &JsonVariant::variantAsObject() const {
   if (_type == Internals::JSON_OBJECT) return *_content.asObject;
   return JsonObject::invalid();
 }
 
-inline Internals::JsonInteger JsonVariant::asInteger() const {
+inline Internals::JsonInteger JsonVariant::variantAsInteger() const {
   using namespace Internals;
   switch (_type) {
     case JSON_UNDEFINED:
@@ -86,7 +86,7 @@ inline Internals::JsonUInt JsonVariant::asUnsignedInteger() const {
   }
 }
 
-inline const char *JsonVariant::asString() const {
+inline const char *JsonVariant::variantAsString() const {
   using namespace Internals;
   if (_type == JSON_UNPARSED && _content.asString &&
       !strcmp("null", _content.asString))
@@ -95,7 +95,7 @@ inline const char *JsonVariant::asString() const {
   return NULL;
 }
 
-inline Internals::JsonFloat JsonVariant::asFloat() const {
+inline Internals::JsonFloat JsonVariant::variantAsFloat() const {
   using namespace Internals;
   switch (_type) {
     case JSON_UNDEFINED:

include/ArduinoJson/Polyfills/attributes.hpp

@@ -10,7 +10,13 @@
 #ifdef _MSC_VER
 #define FORCE_INLINE __forceinline
 #define NO_INLINE __declspec(noinline)
+#define DEPRECATED(msg) __declspec(deprecated(msg))
 #else
 #define FORCE_INLINE __attribute__((always_inline))
 #define NO_INLINE __attribute__((noinline))
+#if __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 5)
+#define DEPRECATED(msg) __attribute__((deprecated(msg)))
+#else
+#define DEPRECATED(msg) __attribute__((deprecated))
+#endif
 #endif

test/Deprecated_Tests.cpp

@@ -0,0 +1,36 @@
+// Copyright Benoit Blanchon 2014-2017
+// MIT License
+//
+// Arduino JSON library
+// https://github.com/bblanchon/ArduinoJson
+// If you like this project, please add a star!
+
+#define ARDUINOJSON_ENABLE_DEPRECATED 1
+
+#include <ArduinoJson.h>
+#include <gtest/gtest.h>
+
+#if defined(__clang__)
+#pragma clang diagnostic ignored "-Wdeprecated-declarations"
+#elif defined(__GNUC__)
+#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
+#elif defined(_MSC_VER)
+#pragma warning(disable : 4996)
+#endif
+
+TEST(Deprecated, asArray) {
+  DynamicJsonBuffer jsonBuffer;
+  JsonVariant variant = jsonBuffer.createArray();
+  ASSERT_TRUE(variant.asArray().success());
+}
+
+TEST(Deprecated, asObject) {
+  DynamicJsonBuffer jsonBuffer;
+  JsonVariant variant = jsonBuffer.createObject();
+  ASSERT_TRUE(variant.asObject().success());
+}
+
+TEST(Deprecated, asString) {
+  JsonVariant variant = "hello";
+  ASSERT_STREQ("hello", variant.asString());
+}

test/JsonObject_Set_Tests.cpp

@@ -75,7 +75,7 @@ TEST_(StoreArray) {
 
   _object.set("hello", arr);
 
-  EXPECT_EQ(&arr, &_object["hello"].asArray());
+  EXPECT_EQ(&arr, &_object["hello"].as<JsonArray>());
   EXPECT_TRUE(_object["hello"].is<JsonArray&>());
   EXPECT_FALSE(_object["hello"].is<JsonObject&>());
 }
@@ -85,7 +85,7 @@ TEST_(StoreObject) {
 
   _object.set("hello", obj);
 
-  EXPECT_EQ(&obj, &_object["hello"].asObject());
+  EXPECT_EQ(&obj, &_object["hello"].as<JsonObject>());
   EXPECT_TRUE(_object["hello"].is<JsonObject&>());
   EXPECT_FALSE(_object["hello"].is<JsonArray&>());
 }

test/JsonObject_Subscript_Tests.cpp

@@ -85,7 +85,6 @@ TEST_(StoreArray) {
 
   _object["hello"] = arr;
 
-  EXPECT_EQ(&arr, &_object["hello"].asArray());  // <- DEPRECATED
   EXPECT_EQ(&arr, &_object["hello"].as<JsonArray&>());
   EXPECT_EQ(&arr, &_object["hello"].as<JsonArray>());  // <- short hand
   EXPECT_EQ(&arr, &_object["hello"].as<const JsonArray&>());
@@ -102,7 +101,6 @@ TEST_(StoreObject) {
 
   _object["hello"] = obj;
 
-  EXPECT_EQ(&obj, &_object["hello"].asObject());  // DEPRECATED
   EXPECT_EQ(&obj, &_object["hello"].as<JsonObject&>());
   EXPECT_EQ(&obj, &_object["hello"].as<JsonObject>());  // <- short hand
   EXPECT_EQ(&obj, &_object["hello"].as<const JsonObject&>());

test/JsonVariant_Copy_Tests.cpp

@@ -54,7 +54,7 @@ TEST_F(JsonVariant_Copy_Tests, ObjectsAreCopiedByReference) {
 
   object["hello"] = "world";
 
-  EXPECT_EQ(1, _variant1.asObject().size());
+  EXPECT_EQ(1, _variant1.as<JsonObject>().size());
 }
 
 TEST_F(JsonVariant_Copy_Tests, ArraysAreCopiedByReference) {
@@ -64,5 +64,5 @@ TEST_F(JsonVariant_Copy_Tests, ArraysAreCopiedByReference) {
 
   array.add("world");
 
-  EXPECT_EQ(1, _variant1.asArray().size());
+  EXPECT_EQ(1, _variant1.as<JsonArray>().size());
 }

test/JsonVariant_Subscript_Tests.cpp

@@ -22,11 +22,10 @@ TEST_F(JsonVariant_Subscript_Tests, Array) {
   _variant = array;
 
   EXPECT_EQ(2, _variant.size());
-  EXPECT_STREQ("element at index 0", _variant[0].asString());
-  EXPECT_STREQ("element at index 1", _variant[1].asString());
-  EXPECT_STREQ(
-      "element at index 0",
-      _variant[static_cast<unsigned char>(0)].asString());  // issue #381
+  EXPECT_STREQ("element at index 0", _variant[0]);
+  EXPECT_STREQ("element at index 1", _variant[1]);
+  EXPECT_STREQ("element at index 0",
+               _variant[static_cast<unsigned char>(0)]);  // issue #381
   EXPECT_FALSE(_variant[-1].success());
   EXPECT_FALSE(_variant[3].success());
   EXPECT_FALSE(_variant["0"].success());
@@ -40,8 +39,8 @@ TEST_F(JsonVariant_Subscript_Tests, Object) {
   _variant = object;
 
   EXPECT_EQ(2, _variant.size());
-  EXPECT_STREQ("element at key \"a\"", _variant["a"].asString());
-  EXPECT_STREQ("element at key \"b\"", _variant["b"].asString());
+  EXPECT_STREQ("element at key \"a\"", _variant["a"]);
+  EXPECT_STREQ("element at key \"b\"", _variant["b"]);
   EXPECT_FALSE(_variant["c"].success());
   EXPECT_FALSE(_variant[0].success());
 }

test/JsonVariant_Undefined_Tests.cpp

@@ -22,7 +22,7 @@ TEST_F(JsonVariant_Undefined_Tests, AsUnsignedReturns0) {
 }
 
 TEST_F(JsonVariant_Undefined_Tests, AsStringReturnsNull) {
-  EXPECT_EQ(0, variant.asString());
+  EXPECT_EQ(0, variant.as<char*>());
 }
 
 TEST_F(JsonVariant_Undefined_Tests, AsDoubleReturns0) {
@@ -50,9 +50,9 @@ TEST_F(JsonVariant_Undefined_Tests, AsConstObjectReturnInvalid) {
 }
 
 TEST_F(JsonVariant_Undefined_Tests, AsArrayWrapperReturnInvalid) {
-  EXPECT_EQ(JsonArray::invalid(), variant.asArray());
+  EXPECT_EQ(JsonArray::invalid(), variant.as<JsonArray>());
 }
 
 TEST_F(JsonVariant_Undefined_Tests, AsObjectWrapperReturnInvalid) {
-  EXPECT_EQ(JsonObject::invalid(), variant.asObject());
+  EXPECT_EQ(JsonObject::invalid(), variant.as<JsonObject>());
 }