Data Types Used in APIs

The ooRexx APIs rely on a variety of special C++ types for interfacing with the interpreter. Some of these types are specific to the Rexx language, while others are standard types defined by C++. Many of the APIs involve conversion between types, while others require values of a specific type as arguments. This section explains the different types and the rules for using these types.

Rexx Object Types

Open Object Rexx is fundamentally an object-oriented language. All data in the language (including strings and numbers) are represented by object instances. The ooRexx APIs use a number of opaque types that represent instances of Rexx built-in objects. The defined object types are:

RexxObjectPtr

a reference to a Rexx object instance. This is the root of object hierarchy and can represent any type of object.

RexxStringObject

an instance of the Rexx String class. The API set allows String objects to be created and manipulated.

RexxBufferStringObject

an instance of the Rexx String class that can be written into. Buffer strings are used for constructing String objects "in-place" to avoid needing to create a String from a separate buffer. RexxBufferStringObject instances must be finalized to be converted into a usable Rexx String object.

RexxArrayObject

An instance of a Rexx single-dimension array. Arrays are used in many places, and there are interfaces provided for direct array manipulation.

RexxDirectoryObject

An instance of Rexx Directory class. Like arrays, there are APIs provided for access and manipulating data stored in a directory.

RexxStemObject

An instance of the Rexx Stem class. The APIs include a number of utility routines for accessing and manipulating data in Stem objects.

RexxSupplierObject

An instance of the Rexx Supplier class.

RexxClassObject

An instance of the Rexx Class class.

RexxPackageObject

An instance of the Rexx Package class.

RexxMethodObject

An instance of the Rexx Method class.

RexxRoutineObject

An instance of the Rexx Routine class. Routine objects can be invoked directly from C++ code.

RexxPointerObject

A wrapper around a pointer value. Pointer objects are designed for constructing Rexx classes that interface with native code subsystems.

RexxBufferObject

An allocatable storage object that can be used for storing native C++ data. Buffer objects and the contained data are managed using the Rexx object garbage collector.

Rexx Numeric Types

The Routine and Method interfaces support a very complete set of C numeric types as arguments and return values. In addition, there are also APIs provided for converting between Rexx Objects and numeric types (and the reverse transformation as well). It is recommended that you allow the Rexx runtime and APIs to handle conversions between Rexx strings and numeric types to give behavior consistent with the Rexx built-in methods and functions.

In addition to a full set of standard numeric types, there are two special types provided that implement the standard Rexx rules for numbers used internally by Rexx. These types are:

wholenumber_t

conversions involving the wholenumber_t conform to the Rexx whole number rules. Values are converted using the same internal digits value used by the built-in functions. For 32-bit versions, this is numeric digits 9, giving a range of 999,999,999 to -999,999,999. On 64-bit systems, numeric digits 18 is used, giving a range of 999,999,999,999,999,999 to -999,999,999,999,999,999.

stringsize_t

stringsize_t conversions also conform to the Rexx whole number rules, with the added restriction that the value must be a non-negative whole number value. The stringsize_t type is useful for arguments such as string lengths where only a non-negative value is allowed. The range for 32-bit versions is 999,999,999 to 0, and 999,999,999,999,999,999 to 0 on 64-bit platforms.

logical_t

a Rexx logical value. On conversion from a string value, this must be either '1' (true) or '0' (false). On conversion back to a string value, a non-zero binary value will be converted to '1' (true) and zero will become '0' (false).

A subset of the integer numeric types are of differing sizes depending on the addressing mode of the system you are compiling on. These types will be either 32-bits or 64-bits. The variable size types are:

size_t

An unsigned "size" value. This is the value type returned by pointer subtraction.

ssize_t

The signed equivalent to size_t.

uintptr_t

An unsigned integer value that's guaranteed to be the same size as a pointer value. Use an uintptr_t type if you wish to return a pointer value as a Rexx number.

intptr_t

A signed equivalent to uintptr_t.

The remainder of the numeric types have fixed sizes regardless of the addressing mode.

int

A 32-bit signed integer.

int32_t

A 32-bit signed integer. This is equivalent to int.

uint32_t

An unsigned 32-bit integer.

int64_t

A signed 64-bit integer.

uint64_t

An unsigned 64-bit integer.

int16_t

A signed 16-bit integer.

uint16_t

An unsigned 16-bit integer.

int8_t

A signed 8-bit integer.

uint8_t

An unsigned 8-bit integer.

float

A 32-bit floating point number. When used as an argument to a routine or method, the strings "nan", "+infinity", and "-infinity" will be converted into the appropriate floating-point values. The reverse conversion is used when converting floating-point values back into Rexx objects.

double

A 64-bit floating point number. The Rexx runtime applies the same special processing for nan, +infinity, and -infinity values as float types.