1.2. Basic Variable Types

1.2. Basic Variable Types
Prev	Chapter 1. How to use this library	Next

ulxmlrpcpp implements all basic variable types from XML-RPC as classes which are derived from a common type Value.

Boolean

Used for the boolean values true and false. Directly corresponds to the C++ type bool.

Integer

Intended for signed integer values that need at most 32bit to store. The C++ type is system dependent and usually an int.

Double

The type of choice for floating point numbers. The range is system dependent but usually around +-1.8E308. The default format for transportation is using only +, -, digits and the decimal point. This leads to large strings for huge values with no actual precision in most of the digits. If you are sure there are no compatibility problems on the other side of your connection you can switch to scientific mode which uses a shorter format with mantissa and exponent like 1.23E-456. This mode is enabled with a call to ulxr::Double::setScientificMode(true)

String

Take this type to pass messages.

There is a pitfall

	There is a pitfall
Since there is no commeon census how characters have to be interpreted and every system uses its own encoding. For that reason ulxmlrpcpp (and `expat` as well) use unicode throughout the complete library. When compiled without Unicode support the internal storage is done in UTF-8 which is a compromise in favour of memory consumption to speed. Earlier versions of ulxmlrpcpp used ISO-8859-1 in this case.

Since there is no commeon census how characters have to be interpreted and every system uses its own encoding. For that reason ulxmlrpcpp (and expat as well) use unicode throughout the complete library. When compiled without Unicode support the internal storage is done in UTF-8 which is a compromise in favour of memory consumption to speed. Earlier versions of ulxmlrpcpp used ISO-8859-1 in this case.

Due to this all you have to take care on how to move your strings into the String type as you must know your encoding when you have characters beyond the ASCII range. If you have iconv installed on your system you may simply convert from your encoding to UTF-8 with encodingToUtf8("your-string", "encoding-name"). ulxmlrpcpp contains some more helper functions to cover the most common conversions without iconv. See Section 1.15, “Worth to Know About UNICODE” for more about this topic.

There is no limitation in the length of the strings nor is there something like a termination character ('\0' in C).

Base64

This type is similar to String but is intended for binary data. Since XML has some limitations in using characters such binary data should be converted for transportation, in this case base64.

For the user this is transparent and you simply store/retrieve your values and the library does the rest.

DateTime

This type is also similar to String but is intended for time values according to the ISO8601 format.. XML-RPC uses only a small subset of this specification. Basically only the 17 characters you need to express a complete timestamp like "20061002T17:26:00" but no details like partial dates, milliseconds or timezones.

Array

This is not really a data type but a possiblity to collect variables. Unlike arrays in many other programming languages an Array may contain different data types. You access the members by their index.

Struct

Similar to the Array type this is also a collection of variables. The difference is that you don't get access by an index but by an identifier. So this is like an associative array or a map in C++.

For convenience reasons there is also the possibility to use streaming-like methods to add parameters to Structs and Arrays. This works similar to the way you would output content to std::cout. To avoid abiguities it is by default not possible to add intrinsic values like int or double. Use Integer or Double if possible. If you really want to handle the built-in types add the following line before the ulxmlrpcpp headers in your sources:


  #define ULXR_USE_INTRINSIC_VALUE_TYPES

Handling the data types might look like this:


  Array arr;
  arr.addItem(Integer(1));
  arr.addItem(String("My String in the array")); 
  arr.addItem(Base64("base64-encoded string"));

  Integer xi = arr.getItem(0); 
  int i = xi.getInteger();
  String xs = arr.getItem(1);
  string s = xs.getString();

  Struct st;
  st.addMember("first member", Double(3.1415)); 
  st.addMember("second member", Boolean(true));

  st << make_member("ima_wstring", String(L"wstring")) 
     << make_member("ima_double", Double(1.0))
     << make_member("ima_bool", Boolean(true));

  Double d = st.getMember("first member");

	Fill an `Array` with some content.
	Access the array, convert to native data type.
	Fill a `Struct` with some values.
	Fill the `Struct` with streaming operators.
	Get a value from the `Struct`.

Note

	Note
In case you should wonder why it is rather complicated to assign values to these types: I did not implement implicit type conversion because I think it leads to subtle errors. The compiler might choose to convert in a totally different way than you might think it should happen. For the same reason there are no overloaded methods like `operator[]` in the `Struct` type. Use the according set/get methods instead, they express exactly what happens.

In case you should wonder why it is rather complicated to assign values to these types:

I did not implement implicit type conversion because I think it leads to subtle errors. The compiler might choose to convert in a totally different way than you might think it should happen. For the same reason there are no overloaded methods like operator[] in the Struct type. Use the according set/get methods instead, they express exactly what happens.