inc/FWebJsonJsonArray.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Apache License, Version 2.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-2.0
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an "AS IS" BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17
  18 /**
  19  * @file                FWebJsonJsonArray.h
  20  * @brief               This is the header file for the %JsonArray class.
  21  *
  22  * This header file contains the declarations of the %JsonArray class.
  23  */
  24 #ifndef _FWEB_JSON_JSON_ARRAY_H_
  25 #define _FWEB_JSON_JSON_ARRAY_H_
  26
  27 #include <FBaseColArrayListT.h>
  28 #include <FBaseColICollectionT.h>
  29 #include <FWebJsonIJsonValue.h>
  30
  31 #ifdef __clang__
  32 #pragma clang diagnostic push
  33 #pragma clang diagnostic ignored "-Woverloaded-virtual"
  34 #endif
  35
  36 namespace Tizen { namespace Web { namespace Json
  37 {
  38 class _JsonArrayImpl;
  39 }}} // Tizen::Web::Json
  40
  41 namespace Tizen { namespace Web { namespace Json
  42 {
  43
  44 /**
  45  * @class       JsonArray
  46  * @brief       This class represents the JSON value of type array.
  47  *
  48  * @since       2.0
  49  *
  50  * @final       This class is not intended for extension.
  51  *
  52  * The %JsonArray class represents the JSON value of type array.
  53  *
  54  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/web/json_namespace.htm">JSON Guide</a>.
  55  *
  56  * The following example demonstrates how to create and initialize a %JsonArray instance and how to use its methods.
  57  *
  58  * @code
  59  *      #include <FWebJson.h>
  60  *
  61  *      using namespace Tizen::Base;
  62  *      using namespace Tizen::Base::Collection;
  63  *      using namespace Tizen::Web::Json;
  64  *
  65  *      void
  66  *      MyClass::JsonArraySample(void)
  67  *      {
  68  *              // Creates an instance of JsonArray
  69  *              JsonArray *pJsonArray = new JsonArray();
  70  *
  71  *              // Must call Construct() for JasonArray
  72  *              pJsonArray->Construct();
  73  *
  74  *              // Creates value instances
  75  *              JsonString  *pJsonstr   = new JsonString(L"myname");
  76  *              JsonNumber  *pJsonNum   = new JsonNumber(99);
  77  *              JsonBool    *pJsonBool  = new JsonBool(true);
  78  *
  79  *              // Adds the string to the JsonArray
  80  *              pJsonArray->Add(pJsonstr);
  81  *              // Adds the number to the JsonArray
  82  *              pJsonArray->Add(pJsonNum);
  83  *              // Adds the boolean to the JsonArray
  84  *              pJsonArray->Add(pJsonBool);
  85  *
  86  *              // Gets the value at the given position(index) in the JsonArray
  87  *              IJsonValue* pValue = null;
  88  *              pJsonArray->GetAt(0, pValue);
  89  *
  90  *              // Finds the index of the given value in the JsonArray
  91  *              JsonString *pJsonstrcheck = new JsonString(L"myname");
  92  *              int index;
  93  *              pJsonArray->IndexOf(pJsonstrcheck, index);
  94  *
  95  *              // Uses enumerator to access elements in the JsonArray
  96  *              IEnumeratorT<IJsonValue*>* pEnum = pJsonArray->GetEnumeratorN();
  97  *              if(pEnum)
  98  *              {
  99  *                      while( pEnum->MoveNext() == E_SUCCESS )
 100  *                      {
 101  *                              IJsonValue* pJsonValue = null;
 102  *
 103  *                              //Uses the pJsonValue
 104  *                              pEnum->GetCurrent( pJsonValue );
 105  *                      }
 106  *                      delete pEnum;
 107  *              }
 108  *
 109  *              // Removes the value in the JsonArray
 110  *              pJsonArray->RemoveAt(index, true);
 111  *
 112  *              // Removes all the remaining values
 113  *              pJsonArray->RemoveAll(true);
 114  *              delete pJsonArray;
 115  *      }
 116  * @endcode
 117  */
 118 class _OSP_EXPORT_ JsonArray
 119         : public IJsonValue
 120         , public Tizen::Base::Collection::ArrayListT<IJsonValue*>
 121 {
 122 public:
 123         /**
 124          * The object is not fully constructed after this constructor is called. @n
 125          * For full construction, the Construct() method must be called right after calling this constructor.
 126          *
 127          * @since       2.0
 128          */
 129         JsonArray(void);
 130
 131         /**
 132          * This destructor overrides Tizen::Base::Object::~Object().
 133          *
 134          * @since       2.0
 135          */
 136         virtual ~JsonArray(void);
 137
 138         /**
 139          * Initializes this instance of %JsonArray.
 140          *
 141          * @since               2.0
 142          *
 143          * @return      An error code
 144          * @exception   E_SUCCESS               The method is successful.
 145          * @exception   E_SYSTEM                This exception exists only for historical reasons.
 146          */
 147         result Construct(void);
 148
 149         /**
 150          * Returns the type of this class. @n
 151          * In this case, it is always @c JSON_ARRAY.
 152          *
 153          * @since       2.0
 154          *
 155          * @return      The JSON type
 156          */
 157         JsonType GetType(void) const;
 158
 159         /**
 160          * Adds the specified element to end of the list.
 161          *
 162          * @since           2.0
 163          *
 164          * @return              An error code
 165          * @param[in]   pJsonValue              A pointer to JsonValue to add to the list
 166          * @exception   E_SUCCESS               The method is successful.
 167          * @exception   E_INVALID_ARG   The specified input parameter is invalid.
 168          * @see                 Remove()
 169          */
 170         virtual result Add(IJsonValue* const& pJsonValue);
 171
 172         /**
 173          * Searches for an element in this list. @n
 174          * Gets the index of the element if it is found.
 175          *
 176          * @since           2.0
 177          *
 178          * @return              An error code
 179          * @param[in]   pJsonValue                      A pointer to the JsonValue class to locate
 180          * @param[out]  index                           The index of the element
 181          * @exception   E_SUCCESS                       The method is successful.
 182          * @exception   E_OBJ_NOT_FOUND         The specified @c pJsonValue is not found.
 183          * @see                 LastIndexOf()
 184          */
 185         virtual result IndexOf(IJsonValue* const& pJsonValue, int& index) const;
 186
 187         /**
 188          * Searches for an element starting from the specified @c index. @n
 189          * Gets the index of the element if it is found.
 190          *
 191          * @since           2.0
 192          *
 193          * @return              An error code
 194          * @param[in]   pJsonValue                      A pointer to the JsonValue class to locate
 195          * @param[in]   startIndex                      The starting index for the search @n
 196          *                                                                      It must be less than the number of elements in the array.
 197          * @param[out]  index                           The index of the element
 198          * @exception   E_SUCCESS                       The method is successful.
 199          * @exception   E_OUT_OF_RANGE          The specified @c index is outside the bounds of the data structure, or the specified @c startIndex is either equal to or greater than the number of elements or less than @c 0.
 200          * @exception   E_OBJ_NOT_FOUND         The specified @c pJsonValue is not found.
 201          * @see                 LastIndexOf()
 202          */
 203         virtual result IndexOf(IJsonValue* const& pJsonValue, int startIndex, int& index) const;
 204
 205         /**
 206          * Searches for an element within the specified range. @n
 207          * Gets the index of the element if it is found.
 208          *
 209          * @since           2.0
 210          *
 211          * @return              An error code
 212          * @param[in]   pJsonValue                      A pointer to the JsonValue class to locate
 213          * @param[in]   startIndex      The starting index of the range
 214          * @param[in]   count                           The number of elements to read
 215          * @param[out]  index                           The index of the element
 216          * @exception   E_SUCCESS                       The method is successful.
 217          * @exception   E_OUT_OF_RANGE          Either of the following conditions has occurred:
 218          *                                                                      - The specified @c index is outside the bounds of the data structure.
 219          *                                                                      - The specified @c startIndex is either greater than or equal to the number of elements or less than @c 0.
 220          *                                                                      - The specified @c count is either greater than the number of elements starting from @c startIndex or less than @c 0.
 221          * @exception   E_OBJ_NOT_FOUND         The specified @c pJsonValue is not found.
 222          * @see                 LastIndexOf()
 223          */
 224         virtual result IndexOf(IJsonValue* const& pJsonValue, int startIndex, int count, int& index) const;
 225
 226         /**
 227          * Searches for the last occurrence of an element in this list. @n
 228          * Gets the index of the element if it is found.
 229          *
 230          * @since           2.0
 231          *
 232          * @return              An error code
 233          * @param[in]   pJsonValue                      A pointer to the JsonValue class to locate
 234          * @param[out]  index                           The index of the last occurrence of the specified element
 235          * @exception   E_SUCCESS                       The method is successful.
 236          * @exception   E_OBJ_NOT_FOUND         The specified @c pJsonValue is not found.
 237          * @see                 IndexOf()
 238          */
 239         virtual result LastIndexOf(IJsonValue* const& pJsonValue, int& index) const;
 240
 241         /**
 242          * Checks whether the list contains the specified @c pJsonValue.
 243          *
 244          * @since           2.0
 245          *
 246          * @return              @c true if the specified @c pJsonValue is present in the list, @n
 247          *                              else @c false
 248          * @param[in]   pJsonValue      A pointer to the JsonValue class to locate
 249          */
 250         virtual bool Contains(IJsonValue* const& pJsonValue) const;
 251
 252         /**
 253          * Checks whether value of the specified instance equals to value of the current instance of %JsonArray.
 254          *
 255          *      @since          2.0
 256          *
 257          * @return              @c true if value of the current instance equals to value of the specified instance, @n
 258          *                              else @c false
 259          * @param[in]   obj                     The element to compare with the current instance of %JsonArray @n
 260          *                                                      If the specified element is not %JsonArray, this method returns @c false.
 261          *  @see                Tizen::Base::Object::Equals()
 262          */
 263         virtual bool Equals(const Object& obj) const;
 264
 265         /**
 266          * Gets the hash value of the current instance.
 267          *
 268          * @since 2.0
 269          *
 270          * @return      An integer value indicating the hash value of the current instance
 271          * @remarks     The two equal instances must return the same hash value. For better performance,
 272          *              the used hash function must generate a random distribution for all inputs.
 273          *              The default implementation of this method returns the address of the current instance.
 274          */
 275         virtual int GetHashCode(void) const;
 276
 277         /**
 278          * Removes the first occurrence of the specified element.
 279          *
 280          * @since           2.0
 281          *
 282          * @return              An error code
 283          * @param[in]   pJsonValue                      A pointer to the JsonValue class to remove
 284          * @param[in]   deallocate                      Set to @c true to deallocate the JsonValue, @n
 285          *                                  else @c false
 286          * @exception   E_SUCCESS                       The method is successful.
 287          * @exception   E_OBJ_NOT_FOUND         The specified @c pJsonValue is not found.
 288          * @see                 Add()
 289          * @see                 RemoveAt()
 290          * @see                 RemoveAll()
 291          */
 292         virtual result Remove(IJsonValue* const& pJsonValue, bool deallocate = false);
 293
 294         /**
 295          * Removes all the elements of the specified @c collection from the list.
 296          *
 297          * @since           2.0
 298          *
 299          * @return              An error code
 300          * @param[in]   collection      The collection to remove from this list
 301          * @param[in]   deallocate                              Set to @c true to deallocate the JsonValues, @n
 302          *                                      else @c false
 303          * @exception   E_SUCCESS                               The method is successful.
 304          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation. @n
 305          *                                                                      The @c collection is modified during the operation of this method.
 306          */
 307         virtual result RemoveItems(const Tizen::Base::Collection::ICollectionT<IJsonValue*>& collection, bool deallocate = false);
 308
 309         /**
 310          * Removes an element from a specified location. @n
 311          * The elements that follow the deleted element move up the list to occupy the empty location.
 312          *
 313          * @since           2.0
 314          *
 315          * @return              An error code
 316          * @param[in]   index                   The index of the element to remove
 317          * @param[in]   deallocate                              Set to @c true to deallocate the JsonValue, @n
 318          *                                      else @c false
 319          * @exception   E_SUCCESS                               The method is successful.
 320          * @exception   E_OUT_OF_RANGE                  The specified @c index is outside the bounds of the data structure, or the specified @c index is greater than or equal to the number of elements or less than @c 0.
 321          */
 322         virtual result RemoveAt(int index, bool deallocate = false);
 323
 324         /**
 325          * Removes all the elements within a specified range. @n
 326          * The elements that follow the deleted elements move up the list to occupy the empty locations.
 327          *
 328          * @since           2.0
 329          *
 330          * @return              An error code
 331          * @param[in]   startIndex      The starting index of the range
 332          * @param[in]   count           The number of elements to remove
 333          * @param[in]   deallocate                              Set to @c true to deallocate the JsonValue, @n
 334          *                                      else @c false
 335          * @exception   E_SUCCESS                               The method is successful.
 336          * @exception   E_OUT_OF_RANGE                  Either of the following conditions has occurred:
 337          *                                                                              - The specified @c startIndex is outside the bounds of the list.
 338          *                                                                              - The specified @c startIndex is either greater than or equal to the number of elements or less than @c 0.
 339          *                                                                              - The specified @c count is either greater than the number of elements starting from @c startIndex or less than @c 0.
 340          */
 341         virtual result RemoveItems(int startIndex, int count, bool deallocate = false);
 342
 343         /**
 344          * Removes all the elements in the %JsonArray class.
 345          *
 346          * @since                2.0
 347          *
 348          * @param[in]   deallocate              Set to @c true to deallocate all the elements, @n
 349          *                              else @c false
 350          */
 351         virtual void RemoveAll(bool deallocate = false);
 352
 353         /**
 354          * Replaces the element at the specified @c index with the specified element.
 355          *
 356          * @since           2.0
 357          *
 358          * @return              An error code
 359          * @param[in]   pJsonValue                      A pointer to the JsonValue class to set
 360          * @param[in]   index                           The index at which the element must be set
 361          * @exception   E_SUCCESS                       The method is successful.
 362          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 363          * @exception   E_OUT_OF_RANGE          The specified @c index is outside the bounds of the data structure, or the specified @c index is either equal to or greater than the number of elements or less than @c 0.
 364          * @see                 GetAt()
 365          */
 366         virtual result SetAt(IJsonValue* const& pJsonValue, int index);
 367
 368         /**
 369          * Replaces the element at the specified @c index with the specified element.
 370          *
 371          * @since               2.0
 372          *
 373          * @return              An error code
 374          * @param[in]   pJsonValue                      A pointer to the JsonValue class to set
 375          * @param[in]   index                           The index at which the element must be set
 376          * @param[in]   deallocate                      Set to @c true to deallocate the JsonValue, @n
 377          *                                  else @c false
 378          * @exception   E_SUCCESS                       The method is successful.
 379          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 380          * @exception   E_OUT_OF_RANGE          The specified @c index is outside the bounds of the data structure, or the specified @c index is either equal to or greater than the number of elements or less than @c 0.
 381          * @see                 GetAt()
 382          */
 383         virtual result SetAt(IJsonValue* const& pJsonValue, int index, bool deallocate);
 384
 385         /**
 386          * Returns a new cloned %JsonArray instance.
 387          *
 388          * @since 2.0
 389          *
 390          * @return              A new cloned %JsonArray or @c null if it fails to allocate the instance
 391          * @exception   E_SUCCESS                       The method is successful.
 392          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 393          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 394          */
 395         JsonArray* CloneN(void) const;
 396
 397 private:
 398         //
 399         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 400         //
 401         // @param[in]   item            The instance of the %JsonArray class to copy from
 402         // @remarks                     This constructor is hidden.
 403         //
 404         JsonArray(const JsonArray& item);
 405
 406         //
 407         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 408         //
 409         // @param[in]   item            The instance of the %JsonArray class to assign from
 410         // @remarks                     This operator is hidden.
 411         //
 412         JsonArray& operator =(const JsonArray& item);
 413
 414 private:
 415         _JsonArrayImpl* __pJsonArrayImpl;
 416
 417         friend class _JsonArrayImpl;
 418 }; // JsonArray
 419
 420 }}} // Tizen::Web::Json
 421 #endif // _FWEB_JSON_JSON_ARRAY_H_
 422
 423 #ifdef __clang__
 424 #pragma clang diagnostic pop
 425 #endif