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 ValueHolder;
45  class IPosition;
46  template<typename T> class Array;
47 
48 
49  // <summary>
50  // Class to hold any JSON value
51  // </summary>
52 
53  // <use visibility=export>
54  // <reviewed reviewer="" date="" tests="tJsonValue">
55  // </reviewed>
56 
57  //# <prerequisite>
58  //# </prerequisite>
59 
60  // <synopsis>
61  // Class JsonValue can hold an arbitrary JSON value which can be a scalar,
62  // a JsonKVMap object, or a vector of JsonValue objects. In this way
63  // JSON values can be nested in any way.
64  //
65  // Internally scalar values are kept as Bool, Int64, Double, DComplex or
66  // String values, but the class has functions to obtain the value in any
67  // data type as long as it can be converted. Note that conversion from
68  // Int64 to Bool is supported.
69  // Null is also a valid JsonValue. A null value can be obtained as a
70  // floating point value resulting in a NaN. For other types an exception
71  // is thrown.
72  //
73  // It is possible to obtain the value as a multi-dimensional Array object
74  // if the values are regular, thus if nested vectors have the same sizes.
75  // The data type of an Array is the 'highest' data type of a value in it.
76  //
77  // Normally a JsonValue objects is created by JsonParser and is the
78  // interface to obtain a value of a filed in a parsed JSON file.
79  // However, users can create JsonValue objects as well.
80  // </synopsis>
81 
82  // <motivation>
83  // JSON is a commonly used interchange format.
84  // </motivation>
85 
86  //# <todo asof="1996/03/10">
87  //# <li>
88  //# </todo>
89 
90  class JsonValue
91  {
92  public:
93  // The default constructor results in a null value.
94  JsonValue();
95 
96  // Construct value with given type.
97  // <group>
98  JsonValue (Bool);
99  JsonValue (int);
100  JsonValue (Int64);
101  JsonValue (double);
102  JsonValue (const DComplex&);
103  JsonValue (const char*);
104  JsonValue (const String&);
105  JsonValue (const std::vector<JsonValue>&);
106  JsonValue (const JsonKVMap&);
107  // </group>
108 
109  // Copy constructor (copy semantics).
110  JsonValue (const JsonValue&);
111 
112  // Assignment (copy semantics).
113  JsonValue& operator= (const JsonValue&);
114 
115  ~JsonValue();
116 
117  // Is the value a null value?
118  Bool isNull() const
119  { return itsValuePtr == 0; }
120 
121  // Is the value a vector?
122  Bool isVector() const
123  { return itsDataType == TpOther; }
124 
125  // Is the value a value map?
126  Bool isValueMap() const
127  { return itsDataType == TpRecord; }
128 
129  // Return the size of a value vector or map (1 is returned for a scalar).
130  size_t size() const;
131 
132  // Get the data type of the value.
133  // A ValueMap is returned as TpRecord, a vector as TpOther.
134  DataType dataType() const
135  { return itsDataType; }
136 
137  // Get the most common data type of the value inside a possibly
138  // nested vector.
139  // <br>- If the value is a single value, that type is returned.
140  // <br>- If any vector value is a ValueMap, TpRecord is returned.
141  // <br>- If any vector contains non-matching data types, TpOther is
142  // returned.
143  // <br>- Otherwise the 'highest' data type is returned.
144  // <group>
145  DataType arrayDataType() const;
146  DataType vectorDataType (const std::vector<JsonValue>& vec) const;
147  // </group>
148 
149  // Get the shape of an array (possibly nested vector).
150  // An exception is thrown if a vector contains a ValueMap or if
151  // the array shape is irregular (nested vectors have different sizes).
152  IPosition shape() const;
153  IPosition vectorShape (const std::vector<JsonValue>& vec) const;
154 
155  // Get the value as a ValueHolder.
156  // An exception is thrown if the value cannot be represented as such,
157  // because it a vector of differently typed values or nested vectors.
158  ValueHolder getValueHolder() const;
159 
160  // Get the value in the given data type.
161  // Numeric data type promotion can be done as well as conversion of
162  // integer to bool (0=False, other=True). An exception is thrown if
163  // a mismatching data type is used.
164  // <group>
165  Bool getBool() const;
166  Int64 getInt() const;
167  double getDouble() const;
168  DComplex getDComplex() const;
169  const String& getString() const;
170  // </group>
171 
172  // As above, but get the value as a vector.
173  // If the value is a scalar, a vector with length 1 is returned.
174  // <group>
175  std::vector<Bool> getVecBool() const;
176  std::vector<Int64> getVecInt() const;
177  std::vector<double> getVecDouble() const;
178  std::vector<DComplex> getVecDComplex() const;
179  std::vector<String> getVecString() const;
180  const std::vector<JsonValue>& getVector() const;
181  // </group>
182 
183  // Get the value as a JsonKVMap (no conversion is possible).
184  const JsonKVMap& getValueMap() const;
185 
186  // Get the value as an Array. The value must be a scalar or a
187  // regularly nested vector.
188  // <group>
189  Array<Bool> getArrayBool() const;
190  Array<Int64> getArrayInt() const;
194  // </group>
195 
196  // Get functions for templated purposes
197  // <group>
198  void get (Bool& value) const
199  { value = getBool(); }
200  void get (Int64& value) const
201  { value = getInt(); }
202  void get (double& value) const
203  { value = getDouble(); }
204  void get (DComplex& value) const
205  { value = getDComplex(); }
206  void get (String& value) const
207  { value = getString(); }
208  void get (std::vector<Bool>& value) const
209  { value = getVecBool(); }
210  void get (std::vector<Int64>& value) const
211  { value = getVecInt(); }
212  void get (std::vector<double>& value) const
213  { value = getVecDouble(); }
214  void get (std::vector<DComplex>& value) const
215  { value = getVecDComplex(); }
216  void get (std::vector<String>& value) const
217  { value = getVecString(); }
218  void get (std::vector<JsonValue>& value) const
219  { value = getVector(); }
220  void get (JsonKVMap& value) const;
221  // </group>
222 
223  // Show value on given ostream.
224  friend ostream& operator<< (ostream&, const JsonValue&);
225 
226  private:
227  // Remove the value.
228  void clear();
229 
230  // Copy the value from another one.
231  void copyValue (const JsonValue& that);
232 
233  // Fill an array from nested vector in a recursive way.
234  template<typename T>
235  T* fillArray (T* data, const T* dataEnd,
236  const std::vector<JsonValue>& vec) const
237  {
238  for (std::vector<JsonValue>::const_iterator iter=vec.begin();
239  iter!=vec.end(); ++iter) {
240  if (iter->dataType() == TpOther) {
241  data = fillArray (data, dataEnd, iter->getVector());
242  } else {
243  AlwaysAssert (data<dataEnd, AipsError);
244  iter->get (*data);
245  data++;
246  }
247  }
248  return data;
249  }
250 
251  DataType itsDataType;
252  void* itsValuePtr;
253  };
254 
255 
256 } // end namespace
257 
258 #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:134
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:235
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:72
A holder for a value of any basic Casacore data type.
Definition: ValueHolder.h:67
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:251
#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:90
DComplex getDComplex() const
Bool isValueMap() const
Is the value a value map?
Definition: JsonValue.h:126
size_t size() const
Return the size of a value vector or map (1 is returned for a scalar).
ValueHolder getValueHolder() const
Get the value as a ValueHolder.
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:118
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:122
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.