casacore
JsonValue.h
Go to the documentation of this file.
1 //# JsonValue.h: Class to hold any JSON value
2 //# Copyright (C) 2016
3 //# Associated Universities, Inc. Washington DC, USA.
4 //#
5 //# This library is free software; you can redistribute it and/or modify it
6 //# under the terms of the GNU Library General Public License as published by
7 //# the Free Software Foundation; either version 2 of the License, or (at your
8 //# option) any later version.
9 //#
10 //# This library is distributed in the hope that it will be useful, but WITHOUT
11 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13 //# License for more details.
14 //#
15 //# You should have received a copy of the GNU Library General Public License
16 //# along with this library; if not, write to the Free Software Foundation,
17 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18 //#
19 //# Correspondence concerning AIPS++ should be addressed as follows:
20 //# Internet email: aips2-request@nrao.edu.
21 //# Postal address: AIPS++ Project Office
22 //# National Radio Astronomy Observatory
23 //# 520 Edgemont Road
24 //# Charlottesville, VA 22903-2475 USA
25 //#
26 //# $Id: JsonValue.h 14057 2009-09-18 12:26:29Z diepen $
27 
28 #ifndef CASA_JSONVALUE_H
29 #define CASA_JSONVALUE_H
30 
31 //# Includes
32 #include <casacore/casa/BasicSL/String.h>
33 #include <casacore/casa/BasicSL/Complex.h>
34 #include <casacore/casa/Utilities/DataType.h>
35 #include <casacore/casa/Utilities/Assert.h>
36 #include <casacore/casa/Exceptions/Error.h>
37 #include <vector>
38 #include <iosfwd>
39 
40 namespace casacore {
41 
42  //# Forward Declarations
43  class JsonKVMap;
44  class IPosition;
45  template<typename T> class Array;
46 
47 
48  // <summary>
49  // Class to hold any JSON value
50  // </summary>
51 
52  // <use visibility=export>
53  // <reviewed reviewer="" date="" tests="tJsonValue">
54  // </reviewed>
55 
56  //# <prerequisite>
57  //# </prerequisite>
58 
59  // <synopsis>
60  // Class JsonValue can hold an arbitrary JSON value which can be a scalar,
61  // a JsonKVMap object, or a vector of JsonValue objects. In this way
62  // JSON values can be nested in any way.
63  //
64  // Internally scalar values are kept as Bool, Int64, Double, DComplex or
65  // String values, but the class has functions to obtain the value in any
66  // data type as long as it can be converted. Note that conversion from
67  // Int64 to Bool is supported.
68  // Null is also a valid JsonValue. A null value can be obtained as a
69  // floating point value resulting in a NaN. For other types an exception
70  // is thrown.
71  //
72  // It is possible to obtain the value as a multi-dimensional Array object
73  // if the values are regular, thus if nested vectors have the same sizes.
74  // The data type of an Array is the 'highest' data type of a value in it.
75  //
76  // Normally a JsonValue objects is created by JsonParser and is the
77  // interface to obtain a value of a filed in a parsed JSON file.
78  // However, users can create JsonValue objects as well.
79  // </synopsis>
80 
81  // <motivation>
82  // JSON is a commonly used interchange format.
83  // </motivation>
84 
85  //# <todo asof="1996/03/10">
86  //# <li>
87  //# </todo>
88 
89  class JsonValue
90  {
91  public:
92  // The default constructor results in a null value.
93  JsonValue();
94 
95  // Construct value with given type.
96  // <group>
97  JsonValue (Bool);
98  JsonValue (int);
99  JsonValue (Int64);
100  JsonValue (double);
101  JsonValue (const DComplex&);
102  JsonValue (const char*);
103  JsonValue (const String&);
104  JsonValue (const std::vector<JsonValue>&);
105  JsonValue (const JsonKVMap&);
106  // </group>
107 
108  // Copy constructor (copy semantics).
109  JsonValue (const JsonValue&);
110 
111  // Assignment (copy semantics).
112  JsonValue& operator= (const JsonValue&);
113 
114  ~JsonValue();
115 
116  // Is the value a null value?
117  Bool isNull() const
118  { return itsValuePtr == 0; }
119 
120  // Is the value a vector?
121  Bool isVector() const
122  { return itsDataType == TpOther; }
123 
124  // Is the value a value map?
125  Bool isValueMap() const
126  { return itsDataType == TpRecord; }
127 
128  // Return the size of a value vector or map (1 is returned for a scalar).
129  size_t size() const;
130 
131  // Get the data type of the value.
132  // A ValueMap is returned as TpRecord, a vector as TpOther.
133  DataType dataType() const
134  { return itsDataType; }
135 
136  // Get the most common data type of the value inside a possibly
137  // nested vector.
138  // <br>- If the value is a single value, that type is returned.
139  // <br>- If any vector value is a ValueMap, TpRecord is returned.
140  // <br>- If any vector contains non-matching data types, TpOther is
141  // returned.
142  // <br>- Otherwise the 'highest' data type is returned.
143  // <group>
144  DataType arrayDataType() const;
145  DataType vectorDataType (const std::vector<JsonValue>& vec) const;
146  // </group>
147 
148  // Get the shape of an array (possibly nested vector).
149  // An exception is thrown if a vector contains a ValueMap or if
150  // the array shape is irregular (nested vectors have different sizes).
151  IPosition shape() const;
152  IPosition vectorShape (const std::vector<JsonValue>& vec) const;
153 
154  // Get the value in the given data type.
155  // Numeric data type promotion can be done as well as conversion of
156  // integer to bool (0=False, other=True). An exception is thrown if
157  // a mismatching data type is used.
158  // <group>
159  Bool getBool() const;
160  Int64 getInt() const;
161  double getDouble() const;
162  DComplex getDComplex() const;
163  const String& getString() const;
164  // </group>
165 
166  // As above, but get the value as a vector.
167  // If the value is a scalar, a vector with length 1 is returned.
168  // <group>
169  std::vector<Bool> getVecBool() const;
170  std::vector<Int64> getVecInt() const;
171  std::vector<double> getVecDouble() const;
172  std::vector<DComplex> getVecDComplex() const;
173  std::vector<String> getVecString() const;
174  const std::vector<JsonValue>& getVector() const;
175  // </group>
176 
177  // Get the value as a JsonKVMap (no conversion is possible).
178  const JsonKVMap& getValueMap() const;
179 
180  // Get the value as an Array. The value must be a scalar or a
181  // regularly nested vector.
182  // <group>
183  Array<Bool> getArrayBool() const;
184  Array<Int64> getArrayInt() const;
188  // </group>
189 
190  // Get functions for templated purposes
191  // <group>
192  void get (Bool& value) const
193  { value = getBool(); }
194  void get (Int64& value) const
195  { value = getInt(); }
196  void get (double& value) const
197  { value = getDouble(); }
198  void get (DComplex& value) const
199  { value = getDComplex(); }
200  void get (String& value) const
201  { value = getString(); }
202  void get (std::vector<Bool>& value) const
203  { value = getVecBool(); }
204  void get (std::vector<Int64>& value) const
205  { value = getVecInt(); }
206  void get (std::vector<double>& value) const
207  { value = getVecDouble(); }
208  void get (std::vector<DComplex>& value) const
209  { value = getVecDComplex(); }
210  void get (std::vector<String>& value) const
211  { value = getVecString(); }
212  void get (std::vector<JsonValue>& value) const
213  { value = getVector(); }
214  void get (JsonKVMap& value) const;
215  // </group>
216 
217  // Show value on given ostream.
218  friend ostream& operator<< (ostream&, const JsonValue&);
219 
220  private:
221  // Remove the value.
222  void clear();
223 
224  // Copy the value from another one.
225  void copyValue (const JsonValue& that);
226 
227  // Fill an array from nested vector in a recursive way.
228  template<typename T>
229  T* fillArray (T* data, const T* dataEnd,
230  const std::vector<JsonValue>& vec) const
231  {
232  for (std::vector<JsonValue>::const_iterator iter=vec.begin();
233  iter!=vec.end(); ++iter) {
234  if (iter->dataType() == TpOther) {
235  data = fillArray (data, dataEnd, iter->getVector());
236  } else {
237  AlwaysAssert (data<dataEnd, AipsError);
238  iter->get (*data);
239  data++;
240  }
241  }
242  return data;
243  }
244 
245  DataType itsDataType;
246  void* itsValuePtr;
247  };
248 
249 
250 } // end namespace
251 
252 #endif
A Vector of integers, for indexing into Array<T> objects.
Definition: IPosition.h:119
long long Int64
Define the extra non-standard types used by Casacore (like proposed uSize, Size)
Definition: aipsxtype.h:38
std::vector< String > getVecString() const
const std::vector< JsonValue > & getVector() const
DataType dataType() const
Get the data type of the value.
Definition: JsonValue.h:133
IPosition shape() const
Get the shape of an array (possibly nested vector).
const String & getString() const
void clear()
Remove the value.
double getDouble() const
const JsonKVMap & getValueMap() const
Get the value as a JsonKVMap (no conversion is possible).
Array< DComplex > getArrayDComplex() const
Array< Int64 > getArrayInt() const
std::vector< DComplex > getVecDComplex() const
JsonValue & operator=(const JsonValue &)
Assignment (copy semantics).
T * fillArray(T *data, const T *dataEnd, const std::vector< JsonValue > &vec) const
Fill an array from nested vector in a recursive way.
Definition: JsonValue.h:229
Array< String > getArrayString() const
DataType arrayDataType() const
Get the most common data type of the value inside a possibly nested vector.
IPosition vectorShape(const std::vector< JsonValue > &vec) const
Class to hold a collection of JSON key:value pairs.
Definition: JsonKVMap.h:69
Bool getBool() const
Get the value in the given data type.
void copyValue(const JsonValue &that)
Copy the value from another one.
DataType itsDataType
Definition: JsonValue.h:245
#define AlwaysAssert(expr, exception)
These marcos are provided for use instead of simply using the constructors of assert_ to allow additi...
Definition: Assert.h:157
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
Class to hold any JSON value.
Definition: JsonValue.h:89
DComplex getDComplex() const
Bool isValueMap() const
Is the value a value map?
Definition: JsonValue.h:125
size_t size() const
Return the size of a value vector or map (1 is returned for a scalar).
std::vector< double > getVecDouble() const
Array< Bool > getArrayBool() const
Get the value as an Array.
Base class for all Casacore library errors.
Definition: Error.h:135
std::vector< Bool > getVecBool() const
As above, but get the value as a vector.
std::vector< Int64 > getVecInt() const
String: the storage and methods of handling collections of characters.
Definition: String.h:223
Int64 getInt() const
Array< double > getArrayDouble() const
Bool isNull() const
Is the value a null value?
Definition: JsonValue.h:117
this file contains all the compiler specific defines
Definition: mainpage.dox:28
LatticeExprNode value(const LatticeExprNode &expr)
This function returns the value of the expression without a mask.
Bool isVector() const
Is the value a vector?
Definition: JsonValue.h:121
friend ostream & operator<<(ostream &, const JsonValue &)
Show value on given ostream.
DataType vectorDataType(const std::vector< JsonValue > &vec) const
JsonValue()
The default constructor results in a null value.