| The Casbah Project: APIs and Reference Manual: Developer's Release 1 | ||
|---|---|---|
| Prev | The Casbah Project: Casbah Datatypes | Next |
All primitive datatypes are identified by MIME-like id strings.[1]
CaBoolean holds the values TRUE and FALSE. If CaBoolean is represented as an integer, it must use 0 for FALSE and any non-zero value for TRUE.
CaInt8
CaInt16
CaInt32
CaInt64
CaUInt8
CaUInt16
CaUInt32
CaUInt64
CaInts are bit-sized, so CaInt8 holds 8 bits, signed. CaUInt8 holds 8 bits, unsigned. Sizes range from 8 bits to 64 bits.
CaFloat is single-precision and CaDouble is double-precision. Conversion between CaFloat and CaDouble must be provided.
CaDateTime must be able to hold at least the time (in seconds) between Thur Jan 1 00:00:00 1980 and Mon Jan 18 22:14:07 2038. (This is the relative resolution of the 32 bit Unix time_t datatype.) Newer code should use 64 bit representation of the time, allowing a larger time range. All CaDateTime values must be in seconds since Thur Jan 1 00:00:00 1980.
Strings should be in either UTF-8 or UTF-16 format. CaString must be able to hold any character, including the null-byte. [2] The maximum CaString length is 4,294,967,295 characters (2^32 -1).
Holds a sequence of CaUInt8s packed together. [3] The maximum CaBinary size is 4,294,967,295 bytes long (2^32 - 1). Any 8 bit value may be placed in a CaBinary. It must be able to hold embedded null-bytes.
Holds an ordered list of elements. Each element can be any primitive datatype. The following operations must be available on a CaList object.
Table 1. Required CaList operations
Return Value | Method Name | Argument List | Description |
|---|---|---|---|
none | push | (CaObject x) | Push x onto end of list. |
CaObject | pop | () | Remove the last item from the list and return it. |
CaObject | shift | () | Remove the first item from the list and return it. |
none | unshift | (CaObject x) | Push x onto the front of the list; x becomes the first element. |
CaBoolean | contains | (CaObject x) | If the list contains x, return TRUE, otherwise return FALSE. |
CaObject | element_at | (CaUInt64 index) | Return the element at index; the first element is numbered index 0. |
CaUInt64 | length | () | Return the number of elements in the list. |
Note that a language may provide these methods through other means. So long as the operation can be performed (easily) on the list object, it satisfies the requirements. For example, a CaList in Java is best as a java.util.Vector, or in Perl as an array ("@foo").
Holds a paired set of elements. Each pair consists of a key and a value. Both the key and the value can be any primitive datatype. CaDicts associate the value with the key. Keys in a CaDict must be unique.
CaDicts must provide a few primitive operations.
Table 2. Required CaDict Operations
Return Value | Method Name | Argument List | Description |
|---|---|---|---|
CaObject | get | (CaObject key) | Get the value associated with key. |
none | set | (CaObject key, CaObject value) | Set the value associated with key to value. |
CaBoolean | defined | (CaObject key) | Return TRUE if there is a value for key, otherwise return FALSE. |
none | delete | (CaObject key) | Delete the pair denoted by key such that defined will return FALSE for key. |
CaDictIterator | each | () | Iterate over each (key,value) pair in the dictionary. The order that they will be visited in is undefined and left up to the CaDict implementation. |
Note that a language may provide these methods through other means. So long as the operation can be performed (easily) on the list object, it satisfies the requirements. For example, a CaDict in Java is best as a java.util.Hashtable, or in Perl as an array ("%foo").
CaObject is a wildcard datatype: it can hold any other datatype in place of itself. Wherever a CaObject can be stored, any other object can be placed there. This is like id in Objective-C, only any primitive (including CaInt32, etc) can be stored where a CaObject is.
CaNull is the null object. The Casbah null object can be used in anywhere that a CaObject would otherwise have been used. The null object is a special object which has no properties, no values, and no methods or operations applicable to it. Some code may return or pass a null object to signal a certain condition or the absence of any other value to place.
CaTable NEEDS TO BE DOCUMENTED.
| [1] | See MIME and MIME-like Type Identifiers for more details about the use of MIME and MIME-like type identifiers. |
| [2] | All bits are set to zero in the null-byte. |
| [3] | Some specifications refer to this as a sequence of octets, where an octet is an 8 bit value. |