OpenTop namespace:

Overview

Namespace

Class

Glossary

Index

OpenTop Portal

OpenTop 1.5

PREV NAMESPACE NEXT NAMESPACE

FRAMES NO FRAMES

Namespace ot

This is the top-level OpenTop namespace. It contains classes that deal with:-

object lifetime management and garbage collection
multi-threading and synchronization
Unicode string encoding, formatting and conversion
message text retrieval and internationalization
tracing (event logging)

The top-level ot namespace contains classes that support this general-purpose functionality in addition to a number of subordinate namespaces which house classes providing more specialized behaviour.

Class Summary
`ArrayAutoPtr`	A variation of `std::auto_ptr` which holds a pointer to an array and uses the associated `delete` [] syntax when it needs to destroy the array.
`AtomicCounter`	Integer value that can be incremented and decremented. In a multi-threaded environment, access to the counter is synchronized to prevent lost updates.
`AutoBuffer`	An efficient buffer that will automatically grow to hold the required data.
`AutoLock`	Acquires a lock on initialization and releases it on destruction.
`AutoUnlock`	Releases a lock on initialization and re-acquires it on destruction.
`Character`	Represents a Unicode character using an internal sequence of one or more CharType values.
`CodeConverterBase`	Base class that contains enums, values and static methods used by all CodeConverter sub-classes.
`ConditionVariable`	Provides a means for a thread to be signalled when a condition becomes true.
`FastMutex`	Variety of mutex that is optimized and may offer better performance on some platforms.
`ManagedObject`	Common base class for all classes that rely on reference-counting to perform automatic object lifetime management.
`MessageFactory`	Abstract 'interface' class used by OpenTop for locating error and information messages.
`Monitor`	A base class providing both synchronization and notification.
`Mutex`	Multi-threaded synchronization object that enables mutually exclusive access to a protected resource.
`NumUtils`	Class module containing functions to convert numbers into Strings and vice versa.
`ObjectManager`	Manages the lifetime of ManagedObject instances that need to exist for the duration of the application.
`RecursiveMutex`	Variety of mutex that can be locked multiple times by the same thread without blocking.
`RefPtr`	Template class that helps to implement the ManagedObject reference-counting scheme.
`RefPtrMember`	Template class designed to be used as a member variable within a class that needs to store object references, possibly even a reference to itself.
`Runnable`	Abstract 'interface' class which should be implemented by any class whose instances are intended to be executed by a Thread. The derived class must implement the pure virtual `run()` method.
`StringIterator`	Iterator class that will iterate over each Unicode character contained within a controlled sequence of CharType values representing Unicode characters encoded into to the native OpenTop encoding.
`StringUtils`	Class module containing functions to compare and manipulate strings.
`SynchronizedObject`	A Base class facilitating synchronized concurrent access from multiple threads.
`System`	Class module providing useful system-level functions as well as providing a well-known and accessible root from which to navigate to other essential services.
`SystemCodeConverter`	Class module for converting Unicode strings to and from the native OpenTop encoding.
`SystemMonitor`	Application helper class to terminate the OpenTop library cleanly.
`TerminationHandler`	An abstract base class providing an interface for classes that need to be informed when OpenTop is about to terminate.
`Thread`	Class to start and control threads of execution.
`ThreadId`	Represents an abstract thread identifier.
`ThreadLocal`	Provides a class interface to native thread-local storage which provides each thread with its own copy of a variable.
`ThreadTerminationHandler`	An abstract base class providing an interface for classes that need to be informed when OpenTop Threads are about to terminate.
`Tracer`	Provides an abstraction for a run-time tracing service.
`UnicodeCharacterType`	Class module for determining the characteristics of a given Unicode character.

Exception Summary
`Exception`	Base class for all exceptions thrown from the OpenTop library.
`IllegalArgumentException`	Thrown when an illegal argument is passed to a OpenTop method.
`IllegalCharacterException`	Thrown when an illegal character value is detected.
`IllegalMonitorStateException`	Thrown when a Mutex is not in the correct locked state for an operation.
`IllegalStateException`	Thrown when a method is called for an object that is not in the correct state for that operation.
`IllegalThreadStateException`	Thrown when a Thread object is not in the correct state for the method being called. For example, a Thread cannot be started more than once.
`InterruptedException`	Thrown when a thread is waiting, sleeping, or otherwise paused for a long time and another thread interrupts it using Thread::interrupt().
`NullPointerException`	Thrown when a null pointer is passed to a method that requires a valid pointer to be passed.
`OSException`	Thrown when OpenTop makes a system call which results in an unexpected return code.
`RuntimeException`	Base class for exceptions that can be thrown by almost all methods and which are not normally documented in the reference material.
`UnsupportedOperationException`	Thrown when an operation is attempted that is not supported on the current platform.

Typedef Summary
`String`	This typedef determines the String type used by OpenTop.
`ByteString`	This typedef determines the ByteString type used by OpenTop.
`CharType`	Determines the character type used by OpenTop.
`UCharType`	Unsigned version of CharType.
`Byte`	Represents a byte which is an unsigned 8-bit value with a range of 0-255.
`UCS4Char`	Represents an integer type that is capable of holding the code-points for all Unicode characters in the range U+0000 to U+10FFFF.
`UShort`	Convenient type used as an unsigned short integer.
`IntType`	Type used as the return type in operations that need to return either a CharType value or -1 (normally to indicate an End-of-File condition.
`Int64Type`	Represents a large integral value, normally with a size of at least 64 bits.
`UInt64Type`	Represents a large unsigned integral value, normally with a size of at least 64 bits.

Typedefs

Byte

typedef unsigned char Byte

Represents a byte which is an unsigned 8-bit value with a range of 0-255. Bytes are used as the value type when reading or writing external media or communicating with other systems. Bytes are typically converted to and from characters using some form of encoding.

ByteString

typedef OT_BYTE_STRING_TYPE ByteString

This typedef determines the ByteString type used by OpenTop. The type is set equal to the value of the pre-processor macro OT_BYTE_STRING_TYPE which is normally set to std::string.

In OpenTop, a ByteString is simply a sequence of Bytes held within a convenient container. A ByteString is not used to contain strings of Unicode characters - that is the job of String.

Any class name may be defined in the OT_STRING_TYPE macro, but OpenTop requires that the ByteString type supports a set of operations equivalent to those provided by the standard C++ string class std::basic_string<char>.

CharType

typedef OT_CHAR_TYPE CharType

Determines the character type used by OpenTop. The type is set equal to the value of the pre-processor macro OT_CHAR_TYPE which is defined as char unless the OT_WCHAR pre-processor macro is specified, in which case it is defined as wchar_t.

As char is normally only 8-bits wide and wchar_t is only 16-bits wide on some platforms, it is not always possible to store a Unicode character (which has a range from U+0000 - U+10FFFF) into one CharType value. In this case OpenTop represent Unicode characters as a sequence of CharType values representing Unicode characters encoded into to the native OpenTop encoding.

The following table shows how Unicode characters are represented within OpenTop:- as either a single CharType character or a sequence of one or more CharType values encoded using the specified encoding.

Character Type Size (bits) Encoding Max sequence length Pre-processor Macro

char 8 UTF-8 4 -

char 8 ISO-8859-1 1 OT_LATIN1

wchar_t 16 UTF-16 2 OT_WCHAR

wchar_t 32 UCS-4 1 OT_WCHAR

Character Type	Size (bits)	Encoding	Max sequence length	Pre-processor Macro
char	8	UTF-8	4	-
char	8	ISO-8859-1	1	`OT_LATIN1`
wchar_t	16	UTF-16	2	`OT_WCHAR`
wchar_t	32	UCS-4	1	`OT_WCHAR`

See the section on Native OpenTop Character Encoding for further information on how OpenTop encodes Unicode characters.

Int64Type

typedef OT_INT64_TYPE Int64Type

Represents a large integral value, normally with a size of at least 64 bits. On platforms where the long datatype is already 64 bits long (or where there is no native type that is 64 bits long), Int64Type is a typedef for long. On 32-bit Microsoft Windows, Int64Type is a typedef for __int64, and on most UNIX systems it is a typedef for long long.

On platforms that support 64 bit integers, an Int64Type has a range between -9,223,372,036,854,775,808 and 9,223,372,036,854,775,807. Most compilers will require large constant values to be suffixed with an appropriate type specifier (such as 'I64' on Windows and 'LL' on UNIX). To aid portable coding, OpenTop defines the OT_LL macro which can be used for this purpose. e.g:

    Int64Type largeNumber = OT_LL(1000000000000);

See also:: UInt64Type

IntType

typedef OT_INT_TYPE IntType

Type used as the return type in operations that need to return either a CharType value or -1 (normally to indicate an End-of-File condition.

String

typedef OT_STRING_TYPE String

This typedef determines the String type used by OpenTop. The type is set equal to the value of the pre-processor macro OT_STRING_TYPE which is normally defined as std::string (or std::wstring if the OT_WCHAR pre-processor macro is defined).

In OpenTop, a String is treated as a sequence of CharType values representing Unicode characters encoded into to the native OpenTop encoding. Applications must ensure that Strings passed as arguments to OpenmTop functions and methods are suitably encoded. The StringUtils class contains several useful methods for creating String objects.

Any class name may be defined in the OT_STRING_TYPE macro, but OpenTop requires that the String type supports a set of operations equivalent to those provided by the standard C++ string class std::basic_string<T>.

UCharType

typedef OT_UCHAR_TYPE UCharType

Unsigned version of CharType. The CharType typedef usually refers to either a char or wchar_t, which are signed values on some platforms.

The UCharType typedef refers to the same type type as CharType, but it adds an unsigned qualifier on those platforms where CharType represents a signed value.

UCS4Char

typedef unsigned int UCS4Char

Represents an integer type that is capable of holding the code-points for all Unicode characters in the range U+0000 to U+10FFFF. This range requires an integer at least 21 bits wide, so UCS4Char is normally implemented using a 32-bit value.

On some platforms (such as Linux) wchar_t is a 32-bit integer, so UCS4Char and wchar_t are the same. However, on other platforms (such as Microsoft Windows) wchar_t is a 16-bit integer and is therefore incapable of representing the required Unicode range.

UInt64Type

typedef unsigned OT_INT64_TYPE UInt64Type

Represents a large unsigned integral value, normally with a size of at least 64 bits. On platforms where the long datatype is already 64 bits long (or where there is no native type that is 64 bits long), UInt64Type is a typedef for unsigned long. On 32-bit Microsoft Windows, UInt64Type is a typedef for unsigned __int64, and on most UNIX systems it is a typedef for unsigned long long.

On platforms that support 64 bit integers, an UInt64Type has a range between 0 and 18,446,744,073,709,551,616 (2^64).

See also:: Int64Type

UShort

typedef unsigned short UShort

Convenient type used as an unsigned short integer.