wxJSON version 1.0: compatibility breaks

Introduction

This is the first stable release of the wxJSON library. A major version change is the right place to do some reorganization of the API thus introducing some incompatibilities between the new version and the old 0.x versions. The new version also introduces several new features

Compatibility breaks

Note that there is not a 0.x compatibility feature in the new version but the incompatibilities introduced in the new version are very few and very easy to fix.

Invalid JSON objects

In versions 0.x the wxJSONTYPE_EMPTY represents an invalid (not initialized) wxJSONValue object but this is very unreadable. The right type is, of course, INVALID. So, the wxJSONTYPE_EMPTY constant was replaced by wxJSONTYPE_INVALID and the wxJSONValue::IsEmpty() function becomes wxJSONValue::IsValid(). In order to fix this incompatibilty, you have to find-and-replace every occurrence of
 IsEmpty()
with
 !IsValid()   // not IsValid()
.

Integer types

In versions 0.x the wxJSONValue::IsInt64() memberfunction returns TRUE if, and only if, the stored value is of type signed integer and the numeric value is too large to fit in a 32-bit integer. This is wrong, because a number that fits in 32-bits also fits in 64-bits

In the new 1.0 version, the IsXxxxxx() functions will return TRUE if the stored value can be represented in the requested data type without any changes in the stored memory bits. So all integers can be stored in a 64-bits integer. The IsInt64() function will, therefore, return TRUE if the stored value is of type signed integer, regardless its size.

This new organization of the IsXxxxxx() memberfunction is incompatible only for integer types. Also note that the incompatibility only happens if a specific check order is in effect. For example, suppose we store the signed integer value of 100 in a JSON value object and want to retrive the value:

  wxJSONValue v( 100 );

  if ( v1.IsInt())  {      // because we first check the smallest integer
    int i = v.AsInt();     // size, we get the same results in 0.x and 1.0
  }
  else if ( v1.IsInt64())  {
    wxInt64 i64 = v.AsInt64();
  }
  else if ....

The above code fragment is compatible with the past because we first check the integer type with the smallest storage size. If the conditional expressions were written in the reverse order the value would be stored in the i64 variable which is not an error but, maybe, it is not want you wanted. To know more about integer storage read 64-bits and 32-bits integers.

Also note that the new integer data types handled by 1.0 version introduce an incompatibility in the wxJSONValue::GetType() function which now never returns the wxJSONTYPE_INT constant but one of the following:

If your application relies on the int data type and the wxJSONTYPE_INT constant, you have to replace the wxJSONTYPE INT constant with the equivalent that depends on the platform: SHORT or LONG.

Please note that the incompatibility only affects the GetType() function and not the wxJSONValue::IsInt() function which still exists: it returns TRUE if the stored value is of type signed integer and it fits in an int data type regardless its actual size because it relies on the INT_MAX and INT_MIN macros whose value is platform dependent. Hint: if your application is designed to run in many platforms, it is strongly recommended that you never use int as the integer data type because its size is, at minimum, 16-bits wide and not 32 as we are used: for this reason, use long instead of int.

The same applies to unsigned integer data types.

Getting values as compatible types

In versions 0.x the wxJSONValue::AsXxxxxx() functions return the value in the desired type, provided that the stored type is compatible with the one requested. For example, the wxJSONValue::AsDouble() function returns the correct value if the stored type is of type double or integer.

In the new version, the AsXxxxxx() functions return the requested type without reinterpreting the bit representation of the stored value. In other words, if a JSON value contains the signed integer value of -1 (all bits set) the AsDouble() function returns a NaN (all bits set for a double).

Why do I decide to not promote int to double? The answer is simple: if we need to store a JSON integer value in a double data type (but I do not see the reason for doing that) we can simple assign it when we get the value as an integer:

  wxJSONvalue value( -1 );
  double d = value.AsInt();

The above code works fine and it ensures that values are accessed as the stored type. You can also have the value as another type compatible or not and let the compiler warn you if the types are not compatible:

  wxJSONvalue value( -1 );
  double d = value.AsInt();        // works fine
  unsigned int ui = value.AsInt()  // warning: try to assign a signed to unsigned
  wxChar* ch = value.AsInt();      // error: cannot convert int to wxChar*

New features

The new features introduced in the new 1.0 version of the library are contributed by wxJSON users who had modified my sources in order to meet their specific needs. They also sent to me the modified sources so that their code can be merged in the new official release: other users might find these changes very usefull.

New integer types

The following integer data types were implemented in the new 1.0 version: The IsShort() and IsLong() functions return TRUE if the stored value is of type signed integer and the value fits in the specified types. So, for example, if a JSON value object contains the signed integer value of 100, all the following IsXxxxxx functions return TRUE:

To know more about this topic read 64-bits and 32-bits integers.

New flags in the wxJSONWriter class

The wxJSONWriter class needs some more flags in order to remain compatible with the strict JSON syntax and also let the user have complete freedom about styled JSON text output.

To know more about the writer's styles read The wxJSON writer's styles.

Finally, the output of the wxJSONWRITER_NONE style flag has changed a bit: it is not incompatible with the past because the JSON text output is syntactically the same as in previous versions but it differs a bit. To know more about the new style read The wxJSONWRITER_NONE flag.


Generated on Mon Aug 18 22:54:23 2008 for wxJSON by  doxygen 1.4.7