5. Basics: String and Number Objects

Back to Table of Contents

As a convenience, the Daylight Toolkits provide object to hold "ordinary" data -- strings, integers, and floating-point numbers. There is nothing fancy about these objects -- they simply hold a string or numeric value. However, the ability to represent strings and numbers as Toolkit objects makes it possible to attach all kinds of information (e.g. atomic properties, labels, etc.) to other objects, such as atoms, bonds, and molecules. The functions dt_adjunct() and dt_setadjunct() are particularly useful with these simple objects.

5.1 String Objects

A string object is a simple Toolkit object that holds the characters in a string, and the string's length. The Toolkit's concept of a "string" is a series of arbitrary 8-bit values and a length. Note, in particular, that the string is not assumed to be null-terminated, padded with blanks, or other application-language-dependent standards. For example, it is permissible to store arbitrary, or "binary" data in a string object as long as it can be represented as a series of bytes with no machine-dependent word-alignment assumptions.

(Note: Many Toolkit functions return strings. Don't confuse this with functions that return string objects. If a function returns a string object, then the function's return type will be a Handle.)

There is only one function specific to string objects:

dt_alloc_string(string s) => ob

Creates a string object whose contents are identical to s. The string object contains a copy of s rather than a pointer to s, so the application program can discard the original string after calling this function. If s is the invalid string, the string object's contents will be the invalid string.

A string-object's contents can also be modified via the function dt_setstringvalue(), and retrieved with the function dt_stringvalue(); both are discussed in the previous section.

5.2 Integer and Real Number Objects

Integer- and Real-number objects are similar in concept to the string objects described above. Each object type holds a simple number. The following functions operate on these objects:

dt_alloc_integer() => Handle integer_ob

Allocates an integer number object. The object's initial value is zero.

dt_alloc_real() => Handle real_ob

Allocates a real-number object. The object's initial value is zero.

dt_setintegervalue(Handle intob, integer value) => boolean ok

Sets the object's value to value.

dt_setrealvalue(Handle realob, real value) => boolean ok

Sets the object's value to value.

dt_integervalue(Handle intob) => integer i

Returns the integer-object's value.

dt_realvalue(Handle realob) => real r

Returns the real-object's value.

5.3 Binary-Data Functions

It is often convenient to use string objects to store "binary" data -- data that are not intended to be printed, and that may contain "NULL" characters and so forth. However, it is also convenient to be able to represent these binary data as printable ASCII characters. For example, Daylight's THOR database system can store arbitrary binary data, but needs to be able to represent it lexically with a restricted set of printable characters.

Three "convenience" functions are provided to convert binary data to printable ASCII and back again. The conversion used maps each 3 bytes of binary data into 4 bytes of ASCII data (i.e. 4 groups of 6 bits are converted to 4 ASCII characters). The ASCII representation has a trailing byte indicating how many of the last 3 binary bytes are part of the original binary data.

Note that these functions take strings, not string objects, as their inputs, and return string objects, not strings.

dt_ascii2binary(string ascii) => handle string_ob

Convert a binary string to its ASCII representation; returns a newly- allocated string object.

dt_binary2ascii(string binary) => handle string_ob

Convert an ascii representation back to its binary form; returns a newly-allocated string object.

dt_binary2asciilen(string binary) => integer

Returns the length of the string that dt_binary2ascii() would return, but without allocating any object.