The Data Classes

Within Grace, a number of basic classes are used intensively as argument and return objects for other parts of the library. This makes sense, it's what we call eating your own dogfood: a good way to make sure that your product is tasty and nutricious. First we will go over these classes quickly, then we'll illustrate their typical usage through some example code.

The string Class

The most lamented design decision in the C language is the lack of a native string type. There are support groups for people suffering from this oversight. In place of a string type proper, in C there is only the concept of an array of character bytes. The Grace string class is a good alternative for storing static and dynamic string data. Some of its strong points:

• When string data is assigned from another string object, the library uses a copy-on-write mechanism to keep memory usage within bounds: Both strings use the same part of memory until one of them is changed and reserves a private copy.
• Many built-in operations can be performed on the object to help you with common tasks when processing all kinds of text data.
• The string data is kept inside a dynamic buffer that allocates new memory on the go, so there is no such thing as a buffer overflow.
• A string can contain full 8 bit data including NUL characters, so it can double up as a general storage buffer for binary data like bitmaps.

Objects of the string class can be used seamlessly when calling C functions that expect a regular C string. The other way around things are fine, too. If you define functions or methods to accept a string object as an argument, it will accept a C-string just fine.

The statstring Class

Like the regular string class, statstring is a container for string data, but it is optimized for keeping strings that are more static in nature and could be used as an index value for object collections. Alongside the regular string buffer, a calculated hash value is kept inside its objects for this purpose. Within a single thread context, all statstring objects that have the same data point to the same memory region, making it a useful companion for large arrays of indexed sets.

The value Class

A powerful container class for keeping variable data. A value object can contain any of the following:

• Signed or unsigned integer values (8, 16, 32 or 64 bits)
• Strings
• Boolean values
• IP address values
• Fixed point decimal numbers (for currency data).
• Double precision floating point values
• Attributes indexed by a statstring key
• Child value objects (numbered or indexed by statstring key)

The class has all the ingredients for exchanging data without casting the data specification in iron. There are a many ways to serialize and deserialize value objects, with representation formats including:

Format	Read	Write	Attributes	IPv4	Currency
GraceXML	✓	✓	✓	✓	✓
Generic XML with Schemas	✓	✓	✓	✓	✓
Apple plist	✓	✓	-	-	-
Compressed XML	✓	✓	*	*	*
SHoX Binary	✓	✓	✓	✓	✓
CSV	✓	✓	-	-	-
INI	✓	-	-	-	-
PHP Serialized	✓	✓	*	-	-
JSON	✓	✓	-	-	-

In other words, it's extremely easy to connect and talk to the outside world and create easy bindings from your applications for data coming from and going to programs written in other languages.

The currency Class

Class currency is a simple class for fixed point arithmetic, to be used when doing financial calculations that mandate non-use of floating point numbers. It can be formatted for output, externally it is always represented as a cents amount with 2 decimals, internally it currently uses 3 decimals. Beancounters with fixations on regulatory banalities tend to frown upon scary floating point calculations for financial statements; In such a war on your sanity this will be a useful weapon.

The ipaddress Class

For an easy representation of a 32 bits IPv4 address, Grace offers the ipaddress class. It is compatible with the value class for storage and retrieval and serialization. Classes like tcpsocket and tcplistener accept ipaddress objects for binding and connecting.

The timestamp Class

For time keeping and calendar calculations, the timestamp class offers convenient storage, including conversion from popular text-based data/time formats. The class is timezone-aware and can deal with time in a resolution of either seconds or microseconds.

Previous Chapter

Table of Contents

Next Chapter