avoid future accidental use.
See also: DeepDispose::LowFile, OpenLowFile::LowFile
h = gFileHandle(i); object i; int h; |
This method is used to obtain the file handle associated with i
.
n = gName(i); object i; char *n; /* the file name */ |
This method is used to obtain the name of the file represented by i
.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The Number
class is an abstract class used to combine common
functionality of the primitive C numeric data types. Although most of the
functionality is actually implemented in the subclasses of the Number
class, they are documented here because of their common interface.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The Number
class has no specific class methods.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Although most of the instance methods are actually implemented in the
subclasses of the Number
class, they are documented here because
of their common interface. Regardless of the numeric type being
represented there has been every effort made to make a standard set of
interfaces to these data elements. Therefore, you are able to change
the value associated with an instance of the ShortInteger
class
to a double
value of 3.141, however, when you retrieve the
double
value you will only get back 3.0. (Of course you
wouldn’t loose the fractional part if you were dealing with an instance
of the DoubleFloat
class.)
i = gChangeCharValue(i, c); object i; int c; |
This method is used to change the value associated with an instance of
a subclass of the Number
class. Notice that this method
returns the instance being passed. c
is the new value.
If it is not the same type as i
it will be converted.
Note that c
is of type int
. That is because if you pass a
character to a generic function (which uses a variable argument
declaration) the C language will automatically promote it to an
int
.
Example: object x; x = gNewWithChar(Character, 'a'); gChangeCharValue(x, 'b'); |
See also: CharValue::Number
i = gChangeDoubleValue(i, val); object i; double val; |
This method is used to change the value associated with an instance of
a subclass of the Number
class. Notice that this method
returns the instance being passed. val
is the new value.
If it is not the same type as i
it will be converted.
Example: object x; x = gNewWithDouble(DoubleFloat, 3.14); gChangeDoubleValue(x, 7.56); |
See also: NewWithDouble::DoubleFloat, DoubleValue::Number
i = gChangeLongValue(i, val); object i; long val; |
This method is used to change the value associated with an instance of
a subclass of the Number
class. Notice that this method
returns the instance being passed. val
is the new value.
If it is not the same type as i
it will be converted.
Example: object x; x = gNewWithLong(LongInteger, 55L); gChangeLongValue(x, 66L); |
See also: NewWithLong::LongInteger, LongValue::Number
i = gChangeShortValue(i, s); object i; int s; |
This method is used to change the value associated with an instance of
a subclass of the Number
class. Notice that this method
returns the instance being passed. s
is the new value.
If it is not the same type as i
it will be converted.
Note that s
is of type int
. That is because if you pass a
short
to a generic function (which uses a variable argument
declaration) the C language will automatically promote it to an
int
.
Example: object x; x = gNewWithInt(ShortInteger, 55); gChangeShortValue(x, 66); |
See also: NewWithInt::ShortInteger, ShortValue::Number
i = gChangeUShortValue(i, s); object i; unsigned s; |
This method is used to change the value associated with an instance of
a subclass of the Number
class. Notice that this method
returns the instance being passed. s
is the new value.
If it is not the same type as i
it will be converted.
Note that s
is of type unsigned
. That is because if you pass a
short
to a generic function (which uses a variable argument
declaration) the C language will automatically promote it to an
unsigned
.
Example: object x; x = gNewWithUnsigned(UnsignedShortInteger, 55); gChangeUShortValue(x, 66); |
See also: NewWithUnsigned::UnsignedShortInteger
i = gChangeValue(i, v); object i; object v; |
This method is used to change the value associated with an instance of a
subclass of the Number
class. Notice that this method returns
the instance being passed. v
is an object which represents the
new value. If it is not the same type as i
it will be converted.
Note that this conversion does not effect the object v
, just
the value changed in i
.
Example: object x, y; x = gNewWithInt(ShortInteger, 88); y = gNewWithDouble(DoubleFloat, 3.141); gChangeValue(x, y); /* x is changed to 3 */ |
See also: ChangeCharValue::Number, ChangeShortValue::Number, etc.
c = gCharValue(i); object i; char c; |
This method is used to obtain the char
value associated with an
instance of a subclass of the Number
class. Note that this is
one of the few generics which doesn’t return a Dynace object. It
returns a char
. If the instance does not represent an instance
of the Character
class, the returned value of whatever is
represented will be converted to a char
.
Example: object x; char c; x = gNewWithChar(Character, 'a'); c = gCharValue(x); |
See also: NewWithChar::Character, ChangeValue::Number
r = gCompare(i, obj); object i; object obj; int r; |
This method is used by the generic container classes to determine
the relationship of the values represented by i
and obj
.
r
is -1 if the value represented by i
is less than
the value represented by obj
, 1 if the value of i
is greater than obj
, and 0 if they are equal. obj
may be any type of object.
See also: Hash::Number
val = gDoubleValue(i); object i; double val; |
This method is used to obtain the double
value associated
with an instance of a subclass of the Number
class. Note that
this is one of the few generics which doesn’t return a Dynace object.
It returns a double
. If the instance does not represent
an instance of the DoubleFloat
class, the returned value
of whatever is represented will be converted to a double
.
Example: object x; double val; x = gNewWithDouble(DoubleFloat, 7.62); val = gDoubleValue(x); |
See also: NewWithDouble::DoubleFloat, ChangeValue::Number
val = gFormatNumber(i, msk, wth, dp); object i; /* object to be formatted */ char *msk; /* format mask */ int wth; /* field width */ int dp; /* number of decimal places */ object val; /* String value */ |
This method is used to convert a number into a nicely formatted string.
i
is the numeric object to be formatted.
msk
is a character string which tells the formatter specific
which formatting options to use. Each character in the string
represents a different option. The order is not significant. The
following table lists the available options:
B blank if zero C add commas every 3 digits to the left of the decimal point L left justify P put parentheses around negative numbers Z zero fill D floating dollar sign U upper-case letters in conversion (used in bases greater than 10) R add a percent sign to the end of the number |
wth
indicates the width of the field and hence the length of the
resultant String
object. If wth
<= 0 FormatNumber
will
calculate and use the minimum width which will represent i
.
dp
indicates the number of decimal places that should appear in
the string. If dp
is less than the number of decimal places in
i
rounding will occur. However if dp
< 0 Nfmt will
calculate and use the minimum number of decimal places required to fully
represent i
.
The value returned by this method is an instance of the String
class.
Example: object x, y; x = gNewWithDouble(DoubleFloat, 1234567.127); y = gFormatNumber(x, "C", 0, 2); /* y = "1,234,567.13" */ |
See also: StringRepValue::Number
val = gHash(i); object i; int val; |
This method is used by the generic container classes to obtain hash values
for the object. val
is a hash value between 0 and a large integer
value.
See also: Compare::Number
val = gLongValue(i); object i; long val; |
This method is used to obtain the long
value associated
with an instance of a subclass of the Number
class. Note that
this is one of the few generics which doesn’t return a Dynace object.
It returns a long
. If the instance does not represent
an instance of the LongInteger
class, the returned value
of whatever is represented will be converted to a long
.
Example: object x; long val; x = gNewWithLong(LongInteger, 55L); val = gLongValue(x); |
See also: NewWithLong::LongInteger, ChangeLongValue::Number
s = gShortValue(i); object i; short s; |
This method is used to obtain the short
value associated with an
instance of a subclass of the Number
class. Note that this is
one of the few generics which doesn’t return a Dynace object. It
returns a short
. If the instance does not represent an instance
of the ShortInteger
class, the returned value of whatever is
represented will be converted to a short
.
Example: object x; short s; x = gNewWithInt(ShortInteger, 55); s = gShortValue(x); |
See also: NewWithInt::ShortInteger, ChangeShortValue::Number
s = gStringRepValue(i); object i; object s; |
This method is used to generate an instance of the String
class
which represents the value associated with i
. This is often
used to print or display the value. It is also used by
PrintValue::Object
and indirectly by Print::Object
(two methods useful during the debugging phase of a project)
in order to directly print an object’s value.
Example: object x; object s; x = gNewWithInt(ShortInteger, 55); s = gStringRepValue(x); /* s represents "55" */ |
See also: PrintValue::Object, Print::Object, FormatNumber::Number
s = gUnsignedShortValue(i); object i; unsigned short s; |
This method is used to obtain the unsigned short
value associated
with an instance of a subclass of the Number
class. Note that
this is one of the few generics which doesn’t return a Dynace object.
It returns an unsigned short
. If the instance does not represent
an instance of the UnsignedShortInteger
class, the returned value
of whatever is represented will be converted to an unsigned short
.
Example: object x; unsigned short s; x = gNewWithUnsigned(UnsignedShortInteger, 55); s = gUnsignedShortValue(x); |
See also: NewWithUnsigned::UnsignedShortInteger,
ChangeUShortValue::Number
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The NumberArray
class, which is a subclass of Array
, is an
abstract class used to combine common functionality of numeric arrays.
Although most of the functionality is actually implemented in the
subclasses of the NumberArray
class, they are documented here
because of their common interface.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The only class method associated with this class is the New
method
which is used to create new instances of numeric arrays. This method
is actually implemented by subclasses of NumberArray
.
ary = vNew(cls, rnk, ...) object cls, ary; unsigned rnk, ... |
This class method is used to create a new numeric array. This method
is actually implemented by and should only be used with subclasses of
the NumberArray
class. It is documented here because it is the
same for all subclasses of the NumberArray
class.
cls
would be one of the subclasses of the NumberArray
class (such as
CharacterArray
ShortArray
UnsignedShortArray
LongArray
FloatArray
or
DoubleFloatArray
). This will indicate the type of array to be
created.
rnk
is the number of dimensions the new array should have.
The remaining arguments (each of type unsigned) indicates the size of
each consecutive dimension. Note that the number of arguments following
rnk
must be the same as the value in rnk
.
ary
is the new array object created and will be initialized to all
zeros.
Example: object ary; ary = vNew(DoubleFloatArray, 2, 5, 4); /* ary is a 5x4 double matrix */ |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The instance methods associated with this class are actually implemented
by subclasses of NumberArray
. They are documented here because
of their common interface with all subclasses of NumberArray
.
Regardless of the array type, each subclass of NumberArray
implements a full complement of methods necessary to deal with all C
language data types. In all cases, if the value being stored into an
array is not the same as the array, the value being stored will be
converted to the correct type prior to the assignment. Also, if the
desired return type is not the same as the array type, the returned
value will be converted. The type of the array will remain unchanged.
This naturally means that if you store the number 3.141 into an element
of a ShortArray
you will only get 3.0 when attempting to get
back a double
value.
ary = vChangeCharValue(ary, val, ...); object ary; int val; unsigned ... |
This method is used to change the value of one element of
array ary
which should be an instance of a subclass of
NumberArray
.
val
is the value which the element of the array should be changed
to. The reason it is of type int
is because C promotes char
to int
when variable arguments are used.
The arguments after the val
argument (each an unsigned
)
are used to specify the exact index into each consecutive dimension of
the array. The number of arguments after the val
argument
must be equal to the number of dimensions (or rank) of array
ary
. See IndexOrigin::Array
for more information.
If ary
and val
do not represent the same types, normal
data type conversion will take place during the assignment without
changing the type of ary
.
The value returned is the modified array passed.
Example: object ary; ary = vNew(CharacterArray, 2, 5, 4); vChangeCharValue(ary, 'C', 1, 2); /* ary[1][2] <- 'C' */ |
See also: ChangeValue::NumberArray, ChangeDoubleValue::NumberArray,
ChangeCharValue::NumberArray
...
ary = vChangeDoubleValue(ary, val, ...); object ary; double val; unsigned ... |
This method is used to change the value of one element of
array ary
which should be an instance of a subclass of
NumberArray
. This method should also be used for
arrays of type FloatArray
.
val
is the value which the element of the array should be changed
to.
The arguments after the val
argument (each an unsigned
)
are used to specify the exact index into each consecutive dimension of
the array. The number of arguments after the val
argument
must be equal to the number of dimensions (or rank) of array
ary
. See IndexOrigin::Array
for more information.
If ary
and val
do not represent the same types, normal
data type conversion will take place during the assignment without
changing the type of ary
.
The value returned is the modified array passed.
Example: object ary; ary = vNew(DoubleFloatArray, 2, 5, 4); vChangeDoubleValue(ary, 3.141, 1, 2); /* ary[1][2] <- 3.141 */ |
See also: ChangeValue::NumberArray, ChangeCharValue::NumberArray,
ChangeShortValue::NumberArray
...
ary = vChangeLongValue(ary, val, ...); object ary; long val; unsigned ... |
This method is used to change the value of one element of
array ary
which should be an instance of a subclass of
NumberArray
.
val
is the value which the element of the array should be changed
to.
The arguments after the val
argument (each an unsigned
)
are used to specify the exact index into each consecutive dimension of
the array. The number of arguments after the val
argument
must be equal to the number of dimensions (or rank) of array
ary
. See IndexOrigin::Array
for more information.
If ary
and val
do not represent the same types, normal
data type conversion will take place during the assignment without
changing the type of ary
.
The value returned is the modified array passed.
Example: object ary; ary = vNew(LongArray, 2, 5, 4); vChangeLongValue(ary, 27L, 1, 2); /* ary[1][2] <- 27L */ |
See also: ChangeValue::NumberArray, ChangeDoubleValue::NumberArray,
ChangeShortValue::NumberArray
...
ary = vChangeShortValue(ary, val, ...); object ary; int val; unsigned ... |
This method is used to change the value of one element of
array ary
which should be an instance of a subclass of
NumberArray
.
val
is the value which the element of the array should be changed
to. The reason it is of type int
is because C promotes short
to int
when variable arguments are used.
The arguments after the val
argument (each an unsigned
)
are used to specify the exact index into each consecutive dimension of
the array. The number of arguments after the val
argument
must be equal to the number of dimensions (or rank) of array
ary
. See IndexOrigin::Array
for more information.
If ary
and val
do not represent the same types, normal
data type conversion will take place during the assignment without
changing the type of ary
.
The value returned is the modified array passed.
Example: object ary; ary = vNew(ShortArray, 2, 5, 4); vChangeShortValue(ary, 27, 1, 2); /* ary[1][2] <- 27 */ |
See also: ChangeValue::NumberArray, ChangeDoubleValue::NumberArray,
ChangeShortValue::NumberArray
...
ary = vChangeUShortValue(ary, val, ...); object ary; unsigned val; unsigned ... |
This method is used to change the value of one element of
array ary
which should be an instance of a subclass of
NumberArray
.
val
is the value which the element of the array should be changed
to. The reason it is of type unsigned
is because C promotes
unsigned short
to unsigned
when variable arguments are used.
The arguments after the val
argument (each an unsigned
)
are used to specify the exact index into each consecutive dimension of
the array. The number of arguments after the val
argument
must be equal to the number of dimensions (or rank) of array
ary
. See IndexOrigin::Array
for more information.
If ary
and val
do not represent the same types, normal
data type conversion will take place during the assignment without
changing the type of ary
.
The value returned is the modified array passed.
Example: object ary; ary = vNew(UnsignedShortArray, 2, 5, 4); vChangeUShortValue(ary, 27U, 1, 2); /* ary[1][2] <- 27U */ |
See also: ChangeValue::NumberArray, ChangeDoubleValue::NumberArray,
ChangeShortValue::NumberArray
...
ary = vChangeValue(ary, val, ...); object ary; object val; unsigned ... |
This method is used to change the value of one element of array ary
which should be an instance of a subclass of NumberArray
.
val
should be an instance of the Number
class and is the
value which the element of the array should be changed to.
The arguments after the val
argument (each an unsigned
)
are used to specify the exact index into each consecutive dimension of
the array. The number of arguments after the val
argument
must be equal to the number of dimensions (or rank) of array
ary
. See IndexOrigin::Array
for more information.
If ary
and val
do not represent the same types, normal
data type conversion will take place during the assignment without
changing the types of ary
or val
.
The value returned is the modified array passed.
Example: object ary; object v; ary = vNew(DoubleFloatArray, 2, 5, 4); v = gNewWithDouble(Double, 3.141); vChangeValue(ary, v, 1, 2); /* ary[1][2] <- 3.141 */ |
See also: ChangeDoubleValue::NumberArray,
ChangeCharValue::NumberArray ...
v = vCharValue(ary, ...); object ary; unsigned ... char v; |
This method is used to obtain the char
value associated with a
particular element of an instance of a subclass of the
NumberArray
class.
The arguments after the ary
argument (each an unsigned
)
are used to specify the exact index into each consecutive dimension of
the array. The number of arguments after the ary
argument
must be equal to the number of dimensions (or rank) of array
ary
. See IndexOrigin::Array
for more information.
Note that this is one of the few generics which doesn’t return a Dynace
object. It returns a char
. If the instance does not represent
an instance of the CharacterArray
class, the returned value of
whatever is represented will be converted to a char
.
Example: object ary; char v; ary = vNew(CharacterArray, 2, 5, 4); v = vCharValue(ary, 1, 2); /* v has ary[1][2] */ |
See also: ChangeCharValue::NumberArray
v = vDoubleValue(ary, ...); object ary; unsigned ... double v; |
This method is used to obtain the double
value associated with a
particular element of an instance of a subclass of the
NumberArray
class.
The arguments after the ary
argument (each an unsigned
)
are used to specify the exact index into each consecutive dimension of
the array. The number of arguments after the ary
argument
must be equal to the number of dimensions (or rank) of array
ary
. See IndexOrigin::Array
for more information.
Note that this is one of the few generics which doesn’t return a Dynace
object. It returns a double
. If the instance does not represent
an instance of the DoubleFloatArray
class, the returned value of
whatever is represented will be converted to a double
.
Example: object ary; double v; ary = vNew(DoubleFloatArray, 2, 5, 4); v = vDoubleValue(ary, 1, 2); /* v has ary[1][2] */ |
See also: ChangeDoubleValue::NumberArray
v = vLongValue(ary, ...); object ary; unsigned ... long v; |
This method is used to obtain the long
value associated with a
particular element of an instance of a subclass of the
NumberArray
class.
The arguments after the ary
argument (each an unsigned
)
are used to specify the exact index into each consecutive dimension of
the array. The number of arguments after the ary
argument
must be equal to the number of dimensions (or rank) of array
ary
. See IndexOrigin::Array
for more information.
Note that this is one of the few generics which doesn’t return a Dynace
object. It returns a long
. If the instance does not represent
an instance of the LongArray
class, the returned value of
whatever is represented will be converted to a long
.
Example: object ary; long v; ary = vNew(LongArray, 2, 5, 4); v = vLongValue(ary, 1, 2); /* v has ary[1][2] */ |
See also: ChangeLongValue::NumberArray
v = vShortValue(ary, ...); object ary; unsigned ... short v; |
This method is used to obtain the short
value associated with a
particular element of an instance of a subclass of the
NumberArray
class.
The arguments after the ary
argument (each an unsigned
)
are used to specify the exact index into each consecutive dimension of
the array. The number of arguments after the ary
argument
must be equal to the number of dimensions (or rank) of array
ary
. See IndexOrigin::Array
for more information.
Note that this is one of the few generics which doesn’t return a Dynace
object. It returns a short
. If the instance does not represent
an instance of the ShortArray
class, the returned value of
whatever is represented will be converted to a short
.
Example: object ary; short v; ary = vNew(ShortArray, 2, 5, 4); v = vShortValue(ary, 1, 2); /* v has ary[1][2] */ |
See also: ChangeShortValue::NumberArray
v = vUnsignedShortValue(ary, ...); object ary; unsigned ... unsigned short v; |
This method is used to obtain the unsigned short
value associated with a
particular element of an instance of a subclass of the
NumberArray
class.
The arguments after the ary
argument (each an unsigned
)
are used to specify the exact index into each consecutive dimension of
the array. The number of arguments after the ary
argument
must be equal to the number of dimensions (or rank) of array
ary
. See IndexOrigin::Array
for more information.
Note that this is one of the few generics which doesn’t return a Dynace
object. It returns an unsigned short
. If the instance does not represent
an instance of the UnsignedShortArray
class, the returned value of
whatever is represented will be converted to a unsigned short
.
Example: object ary; unsigned short v; ary = vNew(UnsignedShortArray, 2, 5, 4); v = vUnsignedShortValue(ary, 1, 2); /* v has ary[1][2] */ |
See also: ChangeUShortValue::NumberArray
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This class, which is a subclass of Array
, is used to represent
arbitrary shaped arrays of Dynace objects in an efficient manner. By
using ObjectArray
s it is possible to have arrays where each
element contains an arbitrary object including another arrays.
Therefore it is possible to create nested or general arrays which are
nested to arbitrary levels.
Much of the functionality of this class is implemented and documented in
the Array
class. Differences are documented in this section.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The only class method implemented by this class is one used to create
new ObjectArray
instances.
ary = vNew(ObjectArray, rnk, ...) unsigned rnk, ... object ary; |
This class method is used to create a new instance of ObjectArray
.
rnk
is the number of dimensions the new array should have.
The remaining arguments (each of type unsigned) indicates the size of
each consecutive dimension. Note that the number of arguments following
rnk
must be the same as the value in rnk
.
ary
is the new array object created and will be initialized to all
NULL
’s.
Example: object ary; ary = vNew(ObjectArray, 2, 5, 4); /* ary is a 5x4 matrix */ |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Most instance functionality is obtained and documented in the Array
class, however, functionality which is particular to this class is documented
in this section.
v = vValue(ary, ...); object ary; unsigned ... object v; |
This method is used to obtain the object (or NULL) value associated with a
particular element of an instance of the ObjectArray
class.
The arguments after the ary
argument (each an unsigned
)
are used to specify the exact index into each consecutive dimension of
the array. The number of arguments after the ary
argument
must be equal to the number of dimensions (or rank) of array
ary
. See IndexOrigin::Array
for more information.
Example: object ary; object v; ary = vNew(ObjectArray, 2, 5, 4); v = vValue(ary, 1, 2); /* v has ary[1][2] */ |
See also: ChangeValue::ObjectArray
ary = vChangeValue(ary, val, ...); object ary; object val; unsigned ... |
This method is used to change the value of one element of
ObjectArray
ary
.
val
is the value which the element of the array should be changed
to (or NULL).
The arguments after the val
argument (each an unsigned
)
are used to specify the exact index into each consecutive dimension of
the array. The number of arguments after the val
argument
must be equal to the number of dimensions (or rank) of array
ary
. See IndexOrigin::Array
for more information.
The value returned is the modified array passed.
Example: object ary, v; ary = vNew(ObjectArray, 2, 5, 4); v = gNewWithInt(ShortInteger, 6); vChangeValue(ary, v, 1, 2); /* ary[1][2] <- v */ |
See also: Value::ObjectArray
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This class is a subclass of the LookupKey
class. It is used to
associate a value (an arbitrary object) with a key. The documentation
on the LookupKey
should be consulted since much of this class’s
functionality is inherited from it.
See the examples included with the Dynace system for an illustration of the
use of the Set
/Dictionary
related classes.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The only class method associated with this class is the one used to
create instances of the ObjectAssociation
class.
i = gNewWithObjObj(ObjectAssociation, key, val); object key; /* or NULL */ object val; /* or NULL */ object i; |
This class method creates instances of the ObjectAssociation
class.
key
is used to initialize the key associated with the instance
created and val
is used to initialize its associated value. The
new instance is returned.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The instance methods associated with this class are used to obtain,
change and print the value associated with its instances. Much
additional functionality is achieved through its superclass,
LookupKey
.
old = gChangeValue(i, val); object i; object val; /* or NULL */ object old; |
This method is used to change the value associated with ObjectAssociation
i
to a value, val
. The old value is simply no longer
associated with the instance. It is not disposed. This method
returns the old value being replaced.
See also: Value::ObjectAssociation, ChangeKey::LookupKey
c = gDeepCopy(i); object i, c; |
This method is used to create a new instance of the
ObjectAssociation
class which contains a copy of the key
and value from i
. DeepCopy
is used to create the copy of the key and value. The new
ObjectAssociation
instance is returned.
See also: Copy::Object
r = gDeepDispose(i); object i; object r; /* NULL */ |
This method is used to dispose of the instance passed as well as
associated key and value. The key and value are disposed of by using
the DeepDispose
method.
The value returned is always NULL
and may be used to null out
the variable which contained the object being disposed in order to
avoid future accidental use.
See also: DeepDispose::LookupKey
s = gStringRepValue(i); object i; object s; |
This method is used to generate an instance of the String
class
which represents the value associated with i
. This is often
used to print or display the value. It is also used by
PrintValue::Object
and indirectly by Print::Object
(two methods useful during the debugging phase of a project)
in order to directly print an object’s value.
See also: PrintValue::Object, Print::Object
val = gValue(i); object i; object val; |
This method is used to obtain the value associated with
i
.
See also: ChangeValue::ObjectAssociation, Key::LookupKey
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The ObjectPool
class provides a means to group arbitrary objects in a pool.
This pool may later be disposed causing all the objects contained in the pool to
be disposed as well. This is useful when running a particular functional module.
All the new objects can be added to a pool and then disposed en-mass when the functional
unit is complete. This makes object disposal a little easier to organize.
This class can maintain numerous pools as well as global pools.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Class methods for this class are used to create new pools as well as manage global pools.
i = gNew(ObjectPool); object i; |
This class method creates instances of the ObjectPool class. It is usually
only used by subclasses of the ObjectPool
class. The new link
will not point to anything. It will just be an empty link.
This method is actually just inherited from Object
in order
to create a null link.
The value returned is the instance object created (the new link).
See also: Dispose::ObjectPool
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The Pipe
class is used to provide a mechanism for threads
to transfer information via a uni-directional byte stream. If
bi-directional communications is needed two pipes may be used.
The Pipe
class is a subclass of Stream
and as such shares
much of its functionality with other subclasses of the Stream
class. Although this class implements most of its own functionality, it
is documented as part of the Stream
class because most of the
interface is the same for all subclasses of Stream
. Differences
are documented in this section.
See the relevant text for a detailed description of pipes.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
There are only two class methods associated with the Pipe
class.
They are used to create new pipes and find existing ones.
p = gFindStr(Pipe, name) char *name; object p; |
This method is used to obtain a pipe object from its name. p
is the pipe object found or NULL
if not found.
See also: New::Pipe
p = gNew(Pipe) object p; |
This class method is used to create and initialize a new unnamed pipe with a default buffer size.
The value returned (p
) is the pipe object created.
See also: NewWithStrInt::Pipe, FindStr::Pipe, Dispose::Pipe
p = gNewWithStrInt(Pipe, name, bufsiz) char *name; int bufsiz; object p; |
This class method is used to create and initialize a new pipe.
name
is the name of the new pipe and may be NULL
if
no name is to be associated with the pipe.
bufsiz
is the size of the buffer associated with the pipe. The
size of the buffer determines how many bytes of information may be
buffered before a thread has to held. If set too small the system will
become inefficient because of the constant switching between threads.
Typical values are 128 or 512. It depends on the quantity and size of
the data being transferred.
The value returned (p
) is the pipe object created. Other
threads may obtain the thread object by the use of the FindStr::Pipe
method.
See also: New::Pipe, FindStr::Pipe, Dispose::Pipe
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The instance methods associated with this class are used to put bytes on the pipe, take bytes off, dispose of, and obtain information about particular pipes.
Although this class implements most of its own functionality, it is
documented as part of the Stream
class because most of the
interface is the same for all subclasses of Stream
. Differences
are documented in this section.
r = gDeepDispose(p) object p; object r; /* NULL */ |
This method is used to dispose of a pipe instance.
It is the same as Dispose::Pipe
.
The value returned is always NULL
and may be used to null out
the variable which contained the object being disposed in order to
avoid future accidental use.
r = gDispose(p) object p; object r; /* NULL */ |
This method is used to dispose of a pipe instance.
It is the same as DeepDispose::Pipe
.
The value returned is always NULL
and may be used to null out
the variable which contained the object being disposed in order to
avoid future accidental use.
n = gLength(p) object p; long n; |
This method is used to determine the number of bytes currently on
the pipe’s buffer. Note that this method returns a long
.
This is to retain consistency with Length::Stream
.
See also: Room::Pipe, Size::Pipe
p = gMode(p, rblock, wblock) object p; int rblock; /* read block */ int wblock; /* write block */ |
This method is used to set the blocking attributes of a particular
Pipe
.
If blocking is turned on when a particular request for reading or writing occurs and there is insufficient bytes or room available the thread requesting the read or write will go into a hold state until another thread can either supply the requested bytes or make the necessary room available. If blocking is not turned on then the particular read or write request will only perform the operation with as many bytes is available at the time. There will be no waiting.
The rblock
flag effects read requests and the wblock
effects write requests.
This method returns the Pipe
instance passed.
See also: Room::Pipe, Length::Pipe
n = gRoom(p) object p; int n; |
This method is used to determine the number of bytes currently available on the pipe’s buffer.
See also: Length::Pipe
n = gSize(p) object p; int n; |
This method is used to determine the size of the buffer associated with a
Pipe
.
See also: Length::Pipe
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The Pointer
class is used to represent the C language
void *
data type as a Dynace object.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The Pointer class has only one class method and it is used to create new instances of itself.
i = gNewWithPtr(Pointer, val); void *val; object i; |
This class method creates instances of the Pointer class. val
is the initial value of the pointer being represented.
The value returned is a Dynace instance object which represents the pointer passed.
Note that the default disposal methods are used by this class since there are no special storage allocation requirements.
Example: object x; int v = 3; x = gNewWithPtr(Pointer, &v); |
See also: PointerValue::Pointer, Dispose::Object
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The instance methods associated with the Pointer class provide a means of changing and obtaining the value associated with an instance of the Pointer class. Methods are also included to help the generic container classes to quickly access members of this class.
i = gChangeValue(i, val); object i; void *val; |
This method is used to change the value associated with an instance of
the Pointer class. Notice that this method returns the instance
being passed. val
is the new value.
Example: object x; int v1 = 4, v2 = 5; x = gNewWithPtr(Pointer, &v1); gChangeValue(x, &v2); |
See also: NewWithPtr::Pointer, PointerValue::Pointer
r = gCompare(i, obj); object i; object obj; int r; |
This method is used by the generic container classes to determine
the equality of the values represented by i
and obj
.
r
is -1 if the value represented by i
is less than
the value represented by obj
, 1 if the value of i
is greater than obj
, and 0 if they are equal.
See also: Hash::Pointer
val = gHash(i); object i; int val; |
This method is used by the generic container classes to obtain hash values
for the object. val
is a hash value between 0 and a large integer value.
See also: Compare::Pointer
val = gPointerValue(i); object i; void *val; |
This method is used to obtain the void *
value associated with an
instance of the Pointer class. Note that this is one of the few
generics which doesn’t return a Dynace object. It returns a void * pointer.
Example: object x; int a = 4, *b; void *val; x = gNewWithPtr(Pointer, &a); b = (int *) gPointerValue(x); /* b now points to a */ |
See also: NewWithPtr::Pointer, ChangeValue::Pointer
s = gStringRepValue(i); object i; object s; |
This method is used to generate an instance of the String
class
which represents the value associated with i
. This is often
used to print or display the value. It is also used by
PrintValue::Object
and indirectly by Print::Object
(two methods useful during the debugging phase of a project)
in order to directly print an object’s value.
Example: object x; object s; x = gNewWithPtr(Pointer, NULL); s = gStringRepValue(x); |
See also: PrintValue::Object, Print::Object
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This class, which is a subclass of Array
, is used to represent
arbitrary shaped arrays of arbitrary C language pointers in an efficient
manner.
Much of the functionality of this class is implemented and documented in
the Array
class. Differences are documented in this section.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The only class method implemented by this class is one used to create
new PointerArray
instances.
ary = vNew(PointerArray, rnk, ...) unsigned rnk, ... object ary; |
This class method is used to create a new instance of PointerArray
.
rnk
is the number of dimensions the new array should have.
The remaining arguments (each of type unsigned) indicates the size of
each consecutive dimension. Note that the number of arguments following
rnk
must be the same as the value in rnk
.
ary
is the new array object created and will be initialized to
all NULL
’s.
Example: object ary; ary = vNew(PointerArray, 2, 5, 4); /* ary is a 5x4 matrix */ |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Most instance functionality is obtained and documented in the Array
class, however, functionality which is particular to this class is documented
in this section.
v = vPointerValue(ary, ...); object ary; unsigned ... void *v; |
This method is used to obtain the pointer value associated with a
particular element of an instance of the PointerArray
class.
The arguments after the ary
argument (each an unsigned
)
are used to specify the exact index into each consecutive dimension of
the array. The number of arguments after the ary
argument
must be equal to the number of dimensions (or rank) of array
ary
. See IndexOrigin::Array
for more information.
Example: object ary; void *v; ary = vNew(PointerArray, 2, 5, 4); v = vPointerValue(ary, 1, 2); /* v has ary[1][2] */ |
See also: ChangeValue::PointerArray
ary = vChangeValue(ary, val, ...); object ary; void *val; unsigned ... |
This method is used to change the value of one element of
PointerArray
ary
.
val
is the value which the element of the array should be changed
to.
The arguments after the val
argument (each an unsigned
)
are used to specify the exact index into each consecutive dimension of
the array. The number of arguments after the val
argument
must be equal to the number of dimensions (or rank) of array
ary
. See IndexOrigin::Array
for more information.
The value returned is the modified array passed.
Example: object ary; int v = 5; ary = vNew(PointerArray, 2, 5, 4); vChangeValue(ary, &v, 1, 2); /* ary[1][2] <- &v */ |
See also: PointerValue::PointerArray
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Property lists allow arbitrary string name / Dynace object pairs to be associated with any Dynace object. The Dynace objects being associated are associated and retrieved via a unique string name. Any number of these associations may be applied to an instance of a class with this capability.
This class is used as a mixin class. A mixin class is one which is sub-classed with another class (multiple inheritance) in order to give additional functionality to the first class. This class gives any class which inherits from it the ability to set and retrieve arbitrary Dynace objects which are accessed by string names (properties).
For example, if you had a class called MyClass
and wanted to give it
the ability to have property lists you would create a new class called
MyClassWithProperties
(for example) which would inherit from
MyClass
and PropertyList
. The new class (MyClassWithProperties
)
would contain all the functionality of MyClass
plus it would be able
to handle property lists.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
There are no class methods implemented by this class.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
r = gDisposePropertyList(ins); object ins; /* the instance */ object r; /* ins */ |
This method is used to remove all properties previously associated with an
object. The properties will either be deep disposed or simply disassociated
depending on how they were added (see PropertyPut
). The instance
passed is returned.
Example: gDisposePropertyList(ins); |
See also: PropertyRemove::PropertyList
r = gPropertyGet(ins, pr); object ins; /* the instance */ char *pr; /* the property name */ object r; /* value */ |
This method is used to retrieve a property previously associated with an
object. The property is returned otherwise, if no property with that name
was added, then NULL
is returned.
Example: object val; val = gPropertyGet(ins, "Color"); |
See also: PropertyPut::PropertyList, PropertyRemove::PropertyList
r = gPropertyPut(ins, pr, ad, val); object ins; /* the instance */ char *pr; /* the property name */ int ad; /* auto dispose flag */ object val; /* value to be associated */ object r; /* val */ |
This method is used to associate an object (val
) to instance
ins
under the property name given by pr
. If the given
property has already been used it will be overwritten by val
.
ad
is a flag used to determine what happens to val
once
ins
is disposed or if the property is overwritten. If ad
is 1 the object will be deep disposed otherwise (if it’s zero) it will
be simply disassociated with the object and not disposed.
Example: object ins = gNew(MyClass); gPropertyPut(ins, "Color", 1, gNewWithStr(String, "Red")); |
See also: PropertyGet::PropertyList, PropertyRemove::PropertyList
r = gPropertyRemove(ins, pr); object ins; /* the instance */ char *pr; /* the property name */ object r; /* ins */ |
This method is used to remove a property previously associated with an
object. The property will either be deep disposed or simply disassociated
depending on how it was added (see PropertyPut
). The instance
passed is returned.
Example: gPropertyRemove(ins, "Color"); |
See also: DisposePropertyList::PropertyList, PropertyRemove::PropertyList
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This class provides a mechanism to coordinate the activity of multiple threads. It provides counting, named and unnamed semaphores. See the manual for a detailed description of semaphores.
See the examples included with the Dynace system for an illustration of the use of the thread / pipe / semaphore related classes.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The only two class methods associated with this class provide a means to create new semaphore instances and to find existing semaphores by name.
s = gFindStr(Semaphore, name) char *name; object s; |
This method is used to obtain a semaphore object from its associated name.
If found it is returned, otherwise NULL
is returned.
See also: New::Semaphore
s = gNew(Semaphore) object s; |
This class method is used to create and initialize a new unnamed semaphore with an initial and maximum count of 1.
The value returned (s
) is the semaphore object created.
See also: NewSemaphore::Semaphore, FindStr::Semaphore,
Dispose::Semaphore
s = gNewSemaphore(Semaphore, name, cnt, max) char *name; int cnt, max; object s; |
This class method is used to create and initialize a new semaphore.
name
is the name of the new semaphore and may be NULL
if
no name is to be associated with the semaphore.
cnt
is the initial count associated with the counting semaphore
and is used to indicate the maximum number of threads which may hold
this semaphore at one time. A typical value would be 1 and indicates
that only a single thread may hold it at a time.
max
is the maximum value the count of the semaphore is allowed to
achieve. If set higher (with Release
) it will be reset to
max
. This is typically set to the same value as cnt
.
The value returned (s
) is the semaphore object created. If not
kept it may be obtained later by the use of the FindStr::Semaphore
method.
See also: NewSemaphore::Semaphore, FindStr::Semaphore,
Dispose::Semaphore
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The instance methods associated with this class provide a means for locking, releasing, disposing and getting information about semaphore instances.
cnt = gCount(s) object s; int cnt; |
This method is used to obtain the current lock count associated with
semaphore s
.
See also: New::Semaphore, Name::Semaphore
r = gDeepDispose(s) object s; object r; /* NULL */ |
This method is used to dispose of a semaphore. All locks will be released
and the semaphore is disposed. This method is the same as
Dispose::Semaphore
.
See also: Release::Semaphore
r = gDispose(s) object s; object r; /* NULL */ |
This method is used to dispose of a semaphore. All locks will be released
and the semaphore is disposed. This method is the same as
DeepDispose::Semaphore
.
The value returned is always NULL
and may be used to null out
the variable which contained the object being disposed in order to
avoid future accidental use.
See also: Release::Semaphore
nam = gName(s) object s; char *nam; |
This method is used to obtain the name of semaphore s
.
See also: New::Semaphore, Count::Semaphore
s = gRelease(s, cnt) object s; int cnt; |
This method is used to release a lock on a semaphore. The semaphore
lock count will be incremented by cnt
, which is normally 1.
As soon as a semaphore’s lock count goes above 0 any threads which
are waiting for the semaphore will be taken off hold and receive
the lock (limited to the number of locks available). This method
returns the semaphore instance passed.
See also: WaitFor::Semaphore
r = gWaitFor(s) object s; int r; |
This method is used to obtain a lock on semaphore s
. If the
semaphore has already exceeded its lock count the current thread
will be placed on hold until the semaphore is available. Each call
to WaitFor
uses up a single count associated with semaphore
s
. This method always returns 0.
See also: Release::Semaphore
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The Sequence
class is an abstract class which serves the
sole purpose of grouping several subclasses which have common
functionality. There is no specific class or instance methods
directly associated with this class.
The subclasses of this class (LinkSequence
,
LinkObjectSequence
and SetSequence
) are used to provide a
convenient mechanism to enumerate (or sequence) through all the
elements of a collection.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The Set
class is used to store a collection of objects which
contain some means of unique identification for quick access. The
objects stored may be any Dynace object. gHash
and
gCompare
will be used on the object to be added in order to store
and compare it amongst other objects in the Set
.
Since Dynace contains default methods for Hash
and Compare
,
any group of Dynace objects may be stored in any Set
instance.
If values are to be associated with the keys one of the Dictionary
classes would be preferred. The Set
class, however, provides
most of the functionality needed by the Dictionary
classes.
See the examples included with the Dynace system for an illustration of the
use of the Set
/Dictionary
related classes.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The only class method used in this class is one to create instances of itself.
i = gNew(Set); object i; |
This class method creates instances of the Set
class. The set
created is designed to accommodate rather small sets of about 30
elements. If a Set
becomes too full it automatically re-sizes
itself. See NewWithInt::Set
for a method of creating a set
while specifying its initial size.
The new instance is returned.
See also: NewWithInt::Set, Resize::Set
i = gNewWithInt(Set, size); int size; object i; |
This class method creates instances of the Set
class.
size
is used to give the instance some idea of the initial maximum number
of objects to be stored in the Set
. The actual number of objects may
exceed this number, however, some loss of efficiency will occur.
Since a Set
is implemented as a hash table it is best if size
is actually larger than the number of objects to be held. It should
be an odd number or better yet a prime number. Keep in mind, however,
that there is storage requirements associated with this number and
the use of a very large number will consume large memory resources.
In reality most reasonable numbers will work fine.
Regardless of the size specified the set object will never overflow.
It will just be less efficient if many more elements then size
are added.
The new instance is returned.
See also: New::Set, Resize::Set
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The instance methods associated with this class provide all the means
to add, inquire, remove and print instances of the Set
class.
r = gAdd(i, luk); object i; object luk; object r; |
This method is used to add a new object (luk
) to the Set
instance
(i
). If an object with the same key already exists in the Set
it
will be left as is and Add
will return NULL
. If
luk
is added it will also be returned.
luk
may be any Dynace object. The gHash
and
gCompare
generics are used to find and compare the various
objects in the Set
.
See also: Find::Set, FindAdd::Set, RemoveObj::Set
so = gCopy(i); object i, so; |
This method is used to create a new instance of the Set
class
with the same elements as Set
i
. Or put more simply,
it makes a copy. The new Set
instance is returned.
Note that this method is designed to also work correctly for the
Dictionary
subclasses of Set
.
Example: object x, y; x = gNewWithInt(Set, 101); y = gCopy(x); |
See also: NewWithInt::Set, DeepCopy::Set
so = gDeepCopy(i); object i, so; |
This method is used to create a new instance of the Set
class
which contains copies of all the elements from the original Set
.
DeepCopy
is used on each element to create the copies.
The new Set
instance is returned.
Note that this method is designed to also work correctly for the
Dictionary
subclasses of Set
.
Example: object x, y; x = gNewWithInt(Set, 100); y = gDeepCopy(x); |
See also: NewWithInt::Set, Copy::Set
r = gDeepDispose(i); object i; object r; /* NULL */ |
This method is used to dispose of an entire Set
instance. It also
disposes of all the objects or associations in the Set
by use of the
DeepDispose
method.
The value returned is always NULL
and may be used to null out
the variable which contained the object being disposed in order to
avoid future accidental use.
See also: Dispose::Set, Dispose1::Set, DisposeAllNodes::Set
i = gDeepDisposeAllNodes(i); object i; |
This method is used to remove all objects in a Set
instance
without disposing of the set itself. Each object or association
is disposed of via DeepDispose
.
The value returned is always the instance passed.
See also: DisposeAllNodes::Set, Dispose::Set, DisposeAllNodes1::Set
i = gDeepDisposeGroup(i, fun); object i; int (*fun)(object); |
This method is used to remove and dispose of a group of objects from the
Set
i
. The function, fun
, is executed for each object in
the Set
. With each call fun
is passed the object at that point
in the Set
. If fun
returns a 1 that particular object will be
removed, or else if fun
returns a 0 the object will not be
removed. fun
is used to decide which objects will be removed.
The objects removed are disposed of by use of the DeepDispose
method.
See also: GroupRemove::Set, DisposeGroup::Set, DisposeAllNodes::Set
r = gDeepDisposeObj(i, luk); object i; object luk; object r; |
This method is used to remove and dispose of an object (luk
) from
the Set
instance (i
). If it is not found NULL
is returned,
otherwise i
is returned. luk
is disposed of by use of the
DeepDispose
method.
luk
may be any Dynace object. The gHash
and
gCompare
generics are used to find and compare the various
objects in the Set
.
See also: RemoveObj::Set, DisposeObj::Set
r = gDispose(i); object i; object r; /* NULL */ |
This method is used to dispose of an entire Set
instance.
It does not dispose of any of the objects or associations in the Set
.
The value returned is always NULL
and may be used to null out
the variable which contained the object being disposed in order to
avoid future accidental use.
See also: DeepDispose::Set, Dispose1::Set, DisposeAllNodes::Set
gDispose1(i); object i; |
This method is used to dispose of an entire Set
instance. It also
disposes of all of the objects or associations in the Set
by the use of
the Dispose
method applied to each object. There is no value
returned.
See also: DeepDispose::Set, Dispose::Set, DisposeAllNodes1::Set
i = gDisposeAllNodes(i); object i; |
This method is used to remove all objects in a Set
instance
without disposing of the set itself. It does not dispose of any of the
objects or associations in the Set
, they are simply
disassociated with the Set
.
The value returned is always the instance passed.
See also: DeepDisposeAllNodes::Set, DisposeAllNodes1::Set,
Dispose::Set
i = gDisposeAllNodes1(i); object i; |
This method is used to remove all objects in a Set
instance
without disposing of the set itself. Each object or association in the
set are disposed of via Dispose
.
The value returned is always the instance passed.
See also: DisposeAllNodes::Set, DeepDisposeAllNodes::Set,
Dispose::Set
i = gDisposeGroup(i, fun); object i; int (*fun)(object); |
This method is used to remove and dispose of a group of objects from the
Set
i
. The function, fun
, is executed for each object in
the Set
. With each call fun
is passed the object at that point
in the Set
. If fun
returns a 1 that particular object will be
removed, or else if fun
returns a 0 the object will not be
removed. fun
is used to decide which objects will be removed.
The objects removed are disposed of by use of the Dispose
method.
See also: GroupRemove::Set, DeepDisposeGroup::Set
r = gDisposeObj(i, luk); object i; object luk; object r; |
This method is used to remove and dispose of an object (luk
) from
the Set
instance (i
). If it is not found NULL
is returned,
otherwise i
is returned. luk
is disposed of by use of the
Dispose
method.
luk
may be any Dynace object. The gHash
and
gCompare
generics are used to find and compare the various
objects in the Set
.
See also: RemoveObj::Set, DeepDisposeObj::Set
r = gFind(i, luk); object i; object luk; object r; |
This method is used to find an existing object (luk
) in the
Set
instance (i
). If the object is found in
the Set
it will be returned otherwise Find
will return NULL
.
luk
may be any Dynace object. The gHash
and
gCompare
generics are used to find and compare the various
objects in the Set
.
See also: Add::Set, FindAdd::Set, RemoveObj::Set
r = gFindAdd(i, luk); object i; object luk; object r; |
This method is used to find an existing object (luk
) in the Set
instance (i
) and return it. If the object is not found it will
be added and returned.
luk
may be any Dynace object. The gHash
and
gCompare
generics are used to find and compare the various
objects in the Set
.
See also: Add::Set, Find::Set, RemoveObj::Set
r = gFirst(i); object i; object r; |
This method returns one of the objects in the set. The returned
object will be an arbitrary one in the set. This method is useful
in cases where you want to enumerate through each object in the
set where you will perform some operation on the returned object and
then remove or dispose it from the set. In that case the next call
to gFirst
will simply return a different object from the set.
If no objects are left in the set, gFirst
returns NULL
.
See also: RemoveObj::Set, Sequence::Set
r = gForAll(i, fun); object i; object (*fun)(object); object r; |
This method is used to execute function fun
on each object in a Set
.
Each time fun
is called it is passed the next object in the Set
as its first and only argument. If fun
returns a non-NULL
object, ForAll
returns immediately with the value returned by
fun
. As long as fun
returns NULL it will be passed
successive objects in the Set
until there are no more objects. At
that time ForAll
will just return NULL indicating that all
objects have been enumerated.
See also: Sequence::Set
i = gGroupRemove(i, fun); object i; int (*fun)(object); |
This method is used to remove a group of objects from the Set
i
. The function, fun
, is executed for each
object in the Set
. With each call fun
is passed the
object at that point in the Set
. If fun
returns a 1
that particular object will be removed, or else if fun
returns a 0 the object will not be removed. fun
is used
to decide which objects will be removed.
The objects removed are not disposed.
See also: DisposeGroup::Set, DeepDisposeGroup::Set
r = gRemoveObj(i, luk); object i; object luk; object r; |
This method is used to remove an object (luk
) from the Set
instance (i
) and return it. If the object is not found
NULL
will be returned. luk
is not disposed.
luk
may be any Dynace object. The gHash
and
gCompare
generics are used to find and compare the various
objects in the Set
.
See also: DisposeObj::Set, DeepDisposeObj::Set
r = gResize(i, size); object i; int size; object r; |
This method is used to change the size of the hash table used to
implement the Set
. It may be used if during runtime it is
discovered that the number of objects stored or to be stored in the
Set
are very different than the number used when the Set
was created.
Since a Set
is implemented as a hash table it is best if
size
is actually larger than the number of objects to be held.
It should be an odd number or better yet a prime number. Keep in mind,
however, that there is storage requirements associated with this number
and the use of a very large number will consume large memory resources.
The Set
will support more objects than defined by size
at
a lesser efficiency. In reality most reasonable numbers will work fine.
r
is the re-sized Set
.
This method is very time consuming and should only be used when
absolutely necessary.
See also: NewWithInt::Set
s = gSequence(i); object i; object s; |
This method takes an instance of the Set
class (i
)
and returns an instance of the SetSequence
class
(s
). The Set
represented by i
is not effected by
this operation. The Set
sequence item, s
, is used to enumerate
through all the objects in Set
i
. See the
SetSequence
class for documentation of other methods
needed to use s
.
Example: object set; /* Set */ object s; /* Set sequence */ object obj; /* an object */ /* set must be initialized previously */ for (s=gSequence(set) ; obj = gNext(s) ; ) { /* do something with obj */ } |
See also: Next::SetSequence, First::Set
sz = gSize(i); object i; int sz; |
This method is used to obtain the number of objects in the Set
.
s = gStringRep(i); object i; object s; |
This method is used to generate an instance of the String
class
which represents the object i
and its value. This is often used
to print or display a representation of an object. It is also used by
by Print::Object
(a method useful during the debugging phase of
a project) in order to directly print an object to a stream.
This method obtains the values of each object by calling
StringRepValue
on each element.
See also: Print::Object, PrintValue::Object
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This class is a subclass of Sequence
and is used to provide a
mechanism to enumerate through all the objects in a Set
(or one
of its subclasses) without effecting the structure.
Typically, the Sequence
instance method of the Set
class
is used to create the instances of the SetSequence
class.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
There is only one class method associated with this class. It is used
to create new instances of itself and is only called by the Sequence
method associated with the Set
class.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This class only has a single instance method which is used to enumerate
through objects in the Set
.
obj = gNext(i); object i; object obj; |
This method is used to enumerate through all the objects in a Set
.
Each time Next
is called the following object in the Set
is returned. It does this in a non-destructive way so the associated
Set
is not effected.
When Next
is called after the last object has been returned (or
if there are no objects in the Set
) it will return NULL
and
automatically dispose of the sequence object i
. Therefore,
the only time Dispose
would be needed (if the garbage collector
weren’t being used) would be if the entire list was not enumerated.
Note that if this method is used with one of the Dictionary
classes
each call to Next
returns the appropriate Association
type.
The gValue
and gKey
generics may be used to obtain
the desired values from the Association
returned.
Example: object set; /* Set */ object s; /* Set sequence */ object obj; /* one object or association */ /* set must be initialized previously */ for (s=gSequence(set) ; obj = gNext(s) ; ) { /* do something with object obj */ } |
See also: Sequence::Set
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This class, which is a subclass of NumberArray
, is used to
represent arbitrary shaped arrays of the C language short
data
type in an efficient manner. Although this class implements much of its
own functionality most of it is documented within the NumberArray
and Array
classes because the interface is shared by all
subclasses of the NumberArray
class.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
There is only one class method which is particular to this class.
ary = gIota(ShortArray, n); object ary; int n; |
This method is used to create a ShortArray
which has 1 dimension
of length n
. The first element is initialized with the value
set by IndexOrigin::Array
and each successive element is given
a value one greater than the previous element.
The value returned is the new array.
Example: object ary; ary = gIota(ShortArray, 5); /* ary = (0, 1, 2, 3, 4) */ |
See also: IndexOrigin::Array
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The ShortInteger
class is used to represent the C language
short
data type as a Dynace object. It is a subclass of the
Number
class. Even though the ShortInteger
class
implements most of its own functionality, it is documented as part of
the Number
class because most of the interface is the same for
all subclasses of the Number
class. Differences are documented
in this section.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The ShortInteger
class has only one class method and it is used
to create new instances of itself.
i = gNewWithInt(ShortInteger, s); int s; object i; |
This class method creates instances of the ShortInteger class. s
is the initial value of the integer being represented. Note that
s
is of type int
. That is because if you pass a short
type to a generic function (which uses a variable argument declaration)
the C language will automatically promote it to an int
.
The value returned is a Dynace instance object which represents the integer passed.
Note that the default disposal methods are used by this class since there are no special storage allocation requirements.
Example: object x; x = gNewWithInt(ShortInteger, 55); |
See also: ShortValue::Number, Dispose::Object
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The instance methods associated with the ShortInteger
class
provide a means of changing and obtaining the value associated with an
instance of the ShortInteger
class. All of the
ShortInteger
class instance methods are documented in the
Number
class because of their common interface with all other
subclasses of the Number
class.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The Socket
class is a subclass of Stream
and provides
facilities which make utilizing sockets easy and portable. Sockets
provide a mechanism for network communication over TCP or the Internet.
At present only the client-side methods are implemented.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The only class method is used to open a new socket which equates to forming a connection with a server.
skt = gSocketConnect(Socket, addr, port); char *addr; int port; object skt; |
This method is used to form a connection between a client and server.
The application calling this method would be the client side. In order
to form a connection the IP address (“123.456.789.012”) or domain name
(“prep.ai.mit.edu”) as well as the port number of the server
application must be known. addr
is a character string representing
the IP address or domain name, and port
is the port number for the
server application. This information would always be known by the organization
responsible for the server end.
gSocketConnect
returns an object which represents the connection or
NULL
if the connection was not made.
Example: object skt = gSocketConnect(Socket, "<IP_ADDRESS>", 4099); |
See also: Dispose::Socket
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Instance methods associated with the Socket
class enable data to
be sent to and from a client / server pair of applications.
r = gDispose(skt); object skt; object r; /* NULL */ |
This method is used to close a socket connection and dispose of its
associated object. There is also a gDeepDispose
which performs the
same function.
r = gGetErrorCode(skt); object skt; int r; |
This method is used to obtain an error code which describes the last error on more detail.
r = gRead(skt, buf, n); object skt; char *buf; unsigned n; int r; |
This method is used to read n
bytes into buf
from
Socket
skt
. The value returned is the actual number
of bytes read or -1 on error. An error can occur for two reasons:
a severed connection, or a time out error. In the case of a severed
connection one would not want to continue use of that socket since
it is probably not valid anymore.
gRead
normally waits up to 60 seconds for reception of the
requested bytes. If part of the data is received gRead
will again wait up to 60 seconds for the remaining data. gRead
continues to wait for all the data unless a connection error
occurs or no data is received for at least 60 seconds.
Example: char buf[80]; if (10 != gRead(skt, buf, 10)) error code; |
See also: gTimedRead::Socket
r = gRecvFile(skt, tf); object skt; char *tf; int r; |
This method is used to receive a whole file over a socket connection.
ff
is the name (and path) of the local file to where the received
file is to be saved.
This method returns 0 on success or non-zero upon failure. This method makes some degree of effort (via acknowledgments and check sums) to assure that the file was in fact correctly received.
This method is unique to Dynace which means that the server end would have to have the correct receive function in order for this facility to be used.
Example: if (gRecvFile(skt, "myFile")) handle error; |
See also: SendFile::Socket
r = gSendFile(skt, ff, tf); object skt; char *ff; char *tf; int r; |
This method is used to transmit a whole file over a socket connection.
ff
is the name (and path) of the local file to be transmitted.
tf
is the name of the file that the receiving end will see
(i.e. the name of the file the receiving end will think you are
sending). If tf
is NULL
then ff
is used.
This method returns 0 on success or non-zero upon failure. This method makes some degree of effort (via acknowledgments and check sums) to assure that the file was in fact correctly received by the other end.
This method is unique to Dynace which means that the server end would have to have the correct receive function in order for this facility to be used.
Example: if (gSendFile(skt, "../myFile", NULL)) handle error; |
See also: RecvFile::Socket
r = gTimedRead(skt, buf, n, w); object skt; char *buf; unsigned n; int w; int r; |
This method is used to read n
bytes into buf
from
Socket
skt
. The value returned is the actual number
of bytes read or -1 on error. An error can occur for two reasons:
a severed connection, or a time out error. In the case of a severed
connection one would not want to continue use of that socket since
it is probably not valid anymore.
gTimedRead
normally waits up to w
seconds for reception of the
requested bytes. If part of the data is received gTimedRead
will again wait up to w
seconds for the remaining data. gTimedRead
continues to wait for all the data unless a connection error
occurs or no data is received for at least w
seconds.
Example: char buf[80]; if (10 != gTimedRead(skt, buf, 10, 60)) error code; |
See also: gRead::Socket
r = gTimedWrite(skt, buf, n, w); object skt; char *buf; unsigned n; int w; int r; |
This method is used to send n
bytes from buf
to
Socket
skt
. The value returned is the actual number
of bytes sent or -1 on error. An error can occur for two reasons:
a severed connection, or a time out error. In the case of a severed
connection one would not want to continue use of that socket since
it is probably not valid anymore.
gTimedWrite
normally waits up to w
seconds for the ability to send the
requested bytes. If part of the data is sent gTimedWrite
will again
wait up to w
seconds for the remaining data. gTimedWrite
continues to
wait until all the data is sent unless a connection error occurs
or no data is able to send for at least w
seconds.
Successfully sending data does not guarantee that the data was received on the other end. You must send back some kind of acknowledgement to assure that.
Example: if (12 != gTimedWrite(skt, "Hello, World", 12, 60)) error code; |
See also: gWrite::Socket
r = gWrite(skt, buf, n); object skt; char *buf; unsigned n; int r; |
This method is used to send n
bytes from buf
to
Socket
skt
. The value returned is the actual number
of bytes sent or -1 on error. An error can occur for two reasons:
a severed connection, or a time out error. In the case of a severed
connection one would not want to continue use of that socket since
it is probably not valid anymore.
gWrite
normally waits up to 60 seconds for the ability to send the
requested bytes. If part of the data is sent gWrite
will again
wait up to 60 seconds for the remaining data. gWrite
continues to
wait until all the data is sent unless a connection error occurs
or no data is able to send for at least 60 seconds.
Successfully sending data does not guarantee that the data was received on the other end. You must send back some kind of acknowledgement to assure that.
Example: if (12 != gWrite(skt, "Hello, World", 12)) error code; |
See also: gTimedWrite::Socket
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The Stream
class is an abstract class used to group other classes
which poses the ability to read and write characters sequentially.
Although much of the actual functionality is implemented by its
subclasses, the methods are documented here because of their common
interface.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
There are no class methods associated with this class.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Although most of the following methods are actually implemented in the
subclasses of Stream
, they are documented here because of their
common interface. Note that some methods are not available for all
subclasses of the Stream
class. This would occur if the method
is inappropriate for a particular Stream
subclass (such as
seeking backward on a String
).
r = gAdvance(i, n); object i; long n; long r; |
This method is used to advance the position of the next
read of Stream
i
forward by n
bytes.
The value returned is the actual number of bytes advanced or
0 on error.
See also: Seek::Stream, Retreat::Stream
r = gEndOfStream(i); object i; int r; |
This method returns 1 if Stream
i
is at the end of available
characters and 0 otherwise.
by i
.
See also: Length::Stream, Position::Stream
r = gGets(i, buf, sz); object i; char *buf; int sz; char *r; |
This method is used to read a new-line terminated string from
Stream
i
into buf
. It will read no more than
sz-1
bytes, but room permitting, the new-line will be included.
r
will be the same as buf
unless there is an error, in
which case r
will be NULL
.
Example: char buf[80]; gGets(stdinStream, buf, sizeof buf); |
See also: Read::Stream, Puts::Stream
r = gLength(i); object i; long r; |
This method is used obtain the total length of the Stream
represented
by i
.
See also: Seek::Stream, Position::Stream
r = gPosition(i); object i; long r; |
This method is used obtain the current position in the stream
relative to its beginning.
See also: Seek::Stream, Length::Stream
r = vPrintf(i, fmt, ...); object i; char *fmt; int r; |
This method is used to write a formatted string to stream i
.
fmt
specifies the format of the output as well as the types and
number of remaining arguments. Since this method is implemented by the
use of the vsprintf
function supplied by the host system you may
find more detailed description of the arguments to this method in the
manual supplied by your host compiler (under fprintf
). The only
difference would be the first argument which would now be a Stream
instance.
The value returned is the number of bytes actually written to the stream.
Example: vPrintf(stdoutStream, "I am %d years old.\n", 10); |
See also: Puts::Stream
r = gPutc(i, ch); object i; char ch; int r; |
This method is used to write a character (ch
) to stream i
.
The value returned is the character written or EOF
if error.
Example: gPutc(stdoutStream, 'x'); |
See also: Puts::Stream
r = gPuts(i, str); object i; char *str; /* or: object str; */ int r; |
This method is used to write a string (str
) to stream i
.
str
may also be an instance of the String
class in which
case the associated string will be written. All the characters up to
the first null byte will be written. The value returned is the number
of bytes written to the stream.
Example: gPuts(stdoutStream, "Hello\n"); |
See also: Putc::Stream, Printf::Stream
r = gRead(i, buf, n); object i; char *buf; unsigned n; int r; |
This method is used to read n
bytes into buf
from
Stream
i
. The value returned is the actual number
of bytes read or -1 on error.
Example: char buf[80]; gRead(stdinStream, buf, 10); |
See also: Gets::Stream
r = gRetreat(i, n); object i; long n; long r; |
This method is used to retreat the position of the next
read of Stream
i
by n
bytes.
The value returned is the actual number of bytes retreated or
0 on error.
See also: Seek::Stream, Advance::Stream
r = gSeek(i, n); object i; long n; long r; |
This method is used to seek to position n
of Stream
i
relative to the beginning of the stream.
The value returned is the actual position seeked to or 0 on error.
See also: Retreat::Stream, Advance::Stream
r = gWrite(i, buf, n); object i; char *buf; unsigned n; int r; |
This method is used to write n
bytes from buf
into
Stream
i
. The value returned is the actual number
of bytes written or -1 on error.
Example: gWrite(stdoutStream, "Hello", 5); |
See also: Puts::Stream, Read::Stream
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
There are several global variables associated with the Stream
class. These variables represent standard streams used throughout
Dynace. They are used for diagnostic output as well as any other input
or output which may be necessary on a global basis. These variables may
be assigned different streams in order to redirect the output. The
remainder of this section documents all the global stream variables.
object stderrStream; |
The stderrStream
global variable is used to direct error
messages to the correct output medium. It is initialized to
an instance of the File
class using the C language
stderr
stream. It may be set to any instance of a
subclass of Stream
.
See also: stdoutStream::Stream
object stdinStream; |
The stdinStream
global variable is used as a global mechanism for
obtaining input. It is initialized to an instance of the File
class using the C language stdin
stream. It may be set to any
instance of a subclass of Stream
.
See also: stdoutStream::Stream
object stdoutStream; |
The stdoutStream
global variable is used to direct normal
output to the correct output medium. It is initialized to
an instance of the File
class using the C language
stdout
stream. It may be set to any instance of a
subclass of Stream
.
See also: stderrStream::Stream
object traceStream; |
The traceStream
global variable is used to direct Dynace
trace output to the correct output medium. It is initialized to
an instance of the File
class using the C language
stdout
stream. It may be set to any instance of a
subclass of Stream
.
See also: stderrStream::Stream
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The String
class is used to represent the C language
char *
data type as a Dynace object. It is a subclass
of the Stream
class and it provides an array of methods
to operate on the string objects. Unlike C strings this class will
dynamically expand a string buffer as needed so you should never have to
worry about the buffer size. You can also use the MA_compact
function to compact the string memory and reduce memory fragmentation.
Most of the String
methods which take string arguments (except
the first argument) will accept a C language string (char *
) or
an instance of the String
class arbitrarily. The system can tell
the difference between them at runtime. If it is a valid Dynace object
the system will assure that it is a kind of String
, otherwise
it is assumed to be a C string.
Instances of this class will also operate like other subclasses of
Stream
. That is you can write (append), read (copy and remove),
advance (remove leading characters) and obtain its length. This
comes in handy when you wish to keep a small (and fast) sequential
file in memory.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The String class has several class methods which create new String
instances. They are provided to lend various levels of flexibility.
i = vBuild(String, ...); object i; |
This class method creates a new instance of the String class.
The initial value of the new instance will be the concatenation
of all the String
or char *
arguments up to an END
.
Each argument may be a C language char *
or an instance of the
String
class. Dynace can tell the difference between them at
runtime. If it is a valid Dynace object the system will assure that it is
a kind of String
, otherwise it is assumed to be a C string.
Note that the variable argument list MUST end with an END
.
There is no other way in C to tell when the last argument has been reached.
If you forget the END
the system will probably hang! (If you
have a problem with the system hanging you might want to check all the
vBuild
generic calls.)
The value returned is the new String
instance.
Example: object x, y; x = gNewWithStr(String, " World"); y = vBuild(String, "Hello", x, "!", END); /* y = "Hello World!" */ |
See also: StringValue::String, Dispose::String,
There is also an instance method Build::String
fun = gMaskFunction(String, ch); char ch; int (*fun)(); |
This method is used to return the masking function associated with
the mask character ch
.
Currently there are only two masking characters used in the system,
`#'
(numbers) and `@'
(letters). The `#'
character’s associated function is isdigit
while the `@'
character’s associated function is isalpha
.
The masking function associated with a masking character takes a character as its only parameter and returns non-zero if the character is the masking character associated with the function and returns zero if it is not.
Example: int (*fun)(); char *str = "A1"; int r; fun = gMaskFunction(String, '#'); /* Uses isdigit */ r = fun(str[0]); /* r == 0 */ r = fun(str[1]); /* r == 1 */ |
See also: gSetMaskFiller::String, gApplyMask::String,
gRemoveMask::String
i = gNew(String); object i; |
This class method creates instances of the String class. The returned
String object is initialized to ""
.
The value returned is a Dynace instance object which represents a null string.
Example: object x; x = gNew(String); |
See also: Copy::String, StringValue::String, Dispose::String,
NewWithStr::String, NewWithObj::String
i = gNewWithStr(String, val); char *val; /* or object */ object i; |
This class method creates instances of the String class. val
is the initial value of the string being represented.
val
may be a C language char *
or an instance of the
String
class. Dynace can tell the difference between them at
runtime. If it is a valid Dynace object the system will assure that it is
a kind of String
, otherwise it is assumed to be a C string.
The value returned is a Dynace instance object which represents the string passed.
Example: object x, y; x = gNewWithStr(String, "Hello World!"); y = gNewWithStr(String, (char *) x); |
See also: Copy::String, StringValue::String, Dispose::String
New::String, NewWithObj::String
i = gNewWithObj(String, val); object val; /* or char * */ object i; |
This class method creates instances of the String class. val
is the initial value of the string being represented.
val
may be a C language char *
or an instance of the
String
class. Dynace can tell the difference between them at
runtime. If it is a valid Dynace object the system will assure that it is
a kind of String
, otherwise it is assumed to be a C string.
The value returned is a Dynace instance object which represents the string passed.
Example: object x, y; x = gNewWithObj(String, (object) "Hello World!"); y = gNewWithObj(String, x); |
See also: Copy::String, StringValue::String, Dispose::String
NewWithStr::String, New::String
i = vSprintf(String, fmt, ...); char *fmt; object i; |
This class method creates a new instances of the String class. Except
for the first argument and return value, this method takes the same
arguments and performs the same function as the normal sprintf
contained in your C library. See that documentation.
Note that except for the first argument, this method does not take Dynace objects.
The value returned is a Dynace instance object which represents the result of the operation.
Example: object x; x = vSprintf(String, "%s is %d years old", "John", 66); |
See also: StringValue::String, Dispose::String
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The instance methods associated with the String class provide a means of changing and obtaining the value associated with an instance of the String class. Methods are also included to help the generic container classes to quickly access members of this class.
i = gAppend(i, str); object i; char *str; /* or object */ |
This method is used to append the string represented by str
to the end of the string represented by i
.
str
may be a C language char *
or an instance of the
String
class. Dynace can tell the difference between them at
runtime. If it is a valid Dynace object the system will assure that it is
a kind of String
, otherwise it is assumed to be a C string.
The value returned is the String
instance passed (i
).
Example: object x; x = gNewWithStr(String, "Hello"); gAppend(x, " World!"); /* x = "Hello World!" */ |
See also: ChangeValue::String, Build::String
i = gApplyMask(i, mask, text); object i; char *mask; char *text; |
This method is used to apply mask
to text
and set the
resulting value to i
. If NULL
or an empty string
(""
) is passed in to mask
then i
has its string
value changed to text
. If NULL
or an empty string
(""
) is passed in to text
then mask
is applied
directly to the current string value in i
.
Mask definitions contain any combination of mask characters and literal characters. The first character of a mask can optionally be either ‘>’ or ‘<’ indicating the direction which the mask is applied to the string. If the first character is ‘<’ then the mask is applied from right to left. If the first character is ‘>’ or is neither of the directional characters, then the mask is applied from left to right. The mask character ‘#’ indicates that the character in this position must be a number while the mask character ‘@’ indicates that the character in this position must be a letter. Any other character in the mask is a literal character and is left in the resulting string in its position unchanged.
The value returned is the String
instance passed (i
).
Example: object x; char mask = "<(###) ###-####"; x = gNewWithStr(String, "1234567890"); gApplyMask(x, mask, NULL); /* x = "(123) 456-7890" */ gApplyMask(x, mask, "9876543210"); /* x = "(987) 654-3210" */ gApplyMask(x, NULL, "1234567890"); /* x = "1234567890" */ |
See also: gMaskFunction::String, gSetMaskFiller::String,
gRemoveMask::String
i = vBuild(str, first, ...); object str; char *first; /* or object */ object i; |
This method is used to modify the string associated with instance str
by optionally overwriting and optionally appending a group of C strings or
String
objects.
first
may be an instance of the String
class, a C string
char *
or a NULL
. If first
is NULL
the initial
value of str
will remain intact, otherwise, it will be replaced
with the string represented by first
.
After the first
argument has been processed the remaining
String
or char *
arguments, up to an END
,
will be concatenated to the end of str
.
Each argument may be a C language char *
or an instance of the
String
class. Dynace can tell the difference between them at
runtime. If it is a valid Dynace object the system will assure that it is
a kind of String
, otherwise it is assumed to be a C string.
Note that the variable argument list MUST end with an END
.
There is no other way in C to tell when the last argument has been reached.
If you forget the END
the system will probably hang! (If you
have a problem with the system hanging you might want to check all the
vBuild
generic calls.)
The value returned is the String
instance passed (str
).
Example: object x; x = gNewWithStr(String, "Hello"); vBuild(x, NULL, " World", gNewWithStr(String, "!"), END); /* x = "Hello World!" */ vBuild(x, "Goodbye", " World", "!", END); /* x = "Goodbye World!" */ |
See also: ChangeValue::String, Append::String,
There is also a class method Build::String
i = gChangeCharAt(i, n, c); object i; int n; int c; |
This method is used to change the character at position n
within
String
instance i
to character c
. The index origin
is zero.
If n
is equal to the number of characters in instance i
(that is one greater than the number of indexable characters), string
i
will be extended by one character (c
). However, if any
larger index is used Dynace will issue an error message and abort the
program.
Example: object x; x = gNewWithStr(String, "Hello"); gChangeCharAt(x, 1, 'E'); /* x = "HEllo" */ |
See also: CharValueAt::String
i = gChangeStrValue(i, val); object i; char *val; |
This method is used to change the value associated with an instance of the String class. The new value may be of any length.
The value returned is the instance i
.
Example: object x, y; x = gNewWithStr(String, "Hello World"); gChangeStrValue(x, "Are you all using Dynace?"); |
See also: ChangeValue::String, Append::String, Build::String
i = gChangeValue(i, val); object i; object val; /* or char * */ |
This method is used to change the value associated with an instance of the String class. The new value may be of any length.
val
may be a C language char *
or an instance of the
String
class. Dynace can tell the difference between them at
runtime. If it is a valid Dynace object the system will assure that it is
a kind of String
, otherwise it is assumed to be a C string.
The value returned is the instance i
.
Example: object x, y; x = gNewWithStr(String, "Hello World"); y = gNewWithStr(String, "Are you all using Dynace?"); gChangeValue(x, y); |
See also: ChangeStrValue::String, Append::String, Build::String
c = gCharValueAt(i, n); object i; int n; char c; |
This method is used to obtain character n
from String
instance
i
. The index origin is zero. If an index greater than the available
characters is used Dynace will issue an error message and abort the program.
Example: object x; char c; x = gNewWithStr(String, "Hello"); c = gCharValueAt(x, 1); /* c = 'e' */ |
See also: ChangeCharAt::String
r = gCompare(i, obj); object i; object obj; /* or char * */ int r; |
This method is used to determine the equality of the values represented
by i
and obj
.
obj
may be a C language char *
or an instance of the
String
class. Dynace can tell the difference between them at
runtime. If it is a valid Dynace object the system will assure that it is
a kind of String
, otherwise it is assumed to be a C string.
r
is -1 if the value represented by i
is less than the
value represented by obj
, 1 if the value of i
is greater
than obj
, and 0 if they are equal.
This method is also used by the generic container classes to determine
object relationships.
See also: Equal::String, CompareI::String, CompareN::String
r = gCompareI(i, obj); object i; object obj; /* or char * */ int r; |
This method is used to determine the equality of the values represented
by i
and obj
without regard for the case of the letters.
Therefore, strings such as “abc” and “ABC” will be considered equal.
obj
may be a C language char *
or an instance of the
String
class. Dynace can tell the difference between them at
runtime. If it is a valid Dynace object the system will assure that it is
a kind of String
, otherwise it is assumed to be a C string.
r
is -1 if the value represented by i
is less than the
value represented by obj
, 1 if the value of i
is greater
than obj
, and 0 if they are equal.
See also: Compare::String, CompareN::String
r = gCompareN(i, obj, n); object i; object obj; /* or char * */ int n; /* max number of characters to compare */ int r; |
This method is used to determine the equality of the values represented
by i
and obj
. No more than n
characters will be
compared. If the two strings only differ past n
characters they
will be considered equal.
obj
may be a C language char *
or an instance of the
String
class. Dynace can tell the difference between them at
runtime. If it is a valid Dynace object the system will assure that it is
a kind of String
, otherwise it is assumed to be a C string.
r
is -1 if the value represented by i
is less than the
value represented by obj
, 1 if the value of i
is greater
than obj
, and 0 if they are equal.
See also: Compare::String, CompareNI::String
r = gCompareNI(i, obj, n); object i; object obj; /* or char * */ int n; /* max number of characters to compare */ int r; |
This method is used to determine the equality of the values represented
by i
and obj
without regard for the case of the letters.
Therefore, strings such as “abc” and “ABC” will be considered equal.
No more than n
characters will be compared. If the two strings
only differ past n
characters they will be considered equal.
obj
may be a C language char *
or an instance of the
String
class. Dynace can tell the difference between them at
runtime. If it is a valid Dynace object the system will assure that it is
a kind of String
, otherwise it is assumed to be a C string.
r
is -1 if the value represented by i
is less than the
value represented by obj
, 1 if the value of i
is greater
than obj
, and 0 if they are equal.
See also: CompareI::String, CompareN::String
so = gCopy(i); object i, so; |
This method is used to create a new instance of the String
class
with the same string value as string i
. Or put more simply,
it makes a copy. The new String
instance is returned.
This method performs the same function as DeepCopy::String
.
Example: object x, y; x = gNewWithStr(String, "Hello"); y = gCopy(x); /* x = "Hello" */ |
See also: New::String, DeepCopy::String
so = gDeepCopy(i); object i, so; |
This method is used to create a new instance of the String
class
with the same string value as string i
. Or put more simply,
it makes a copy. The new String
instance is returned.
This method performs the same function as Copy::String
.
Example: object x, y; x = gNewWithStr(String, "Hello"); y = gDeepCopy(x); /* x = "Hello" */ |
See also: New::String, Copy::String
r = gDeepDispose(i); object i; object r; /* NULL */ |
This method is used to dispose of an instance of the String class.
It performs the same operation as Dispose
.
Example: object x; x = gNewWithStr(String, "Hello World"); gDeepDispose(x); |
r = gDispose(i); object i; object r; /* NULL */ |
This method is used to dispose of an instance of the String class.
It performs the same operation as DeepDispose
.
Example: object x; x = gNewWithStr(String, "Hello World"); gDispose(x); |
i = gDrop(i, num); object i; int num; |
This method is used to drop num
characters from string i
.
If num
is positive characters will be dropped from the beginning
of the string, otherwise, characters will be dropped from the end of the
string. An attempt to drop more characters than exist will lead to a
zero length string.
The modified String
instance passed is returned.
Example: object x, y; x = gNewWithStr(String, "Hello World"); gDrop(x, 4); /* x = "o World" */ x = gNewWithStr(String, "Hello World"); gDrop(x, -4); /* x = "Hello W" */ x = gNewWithStr(String, "ABC"); gDrop(x, 5); /* x = "" */ |
See also: Take::String, SubString::String
r = gEqual(i, obj); object i; object obj; /* or char * */ int r; |
This method is used to determine the equality of the values represented
by i
and obj
. If they contain the same string values a
1 is returned and 0 otherwise.
obj
may be a C language char *
or an instance of the
String
class. Dynace can tell the difference between them at
runtime. If it is a valid Dynace object the system will assure that it is
a kind of String
, otherwise it is assumed to be a C string.
Example: object x; int r; x = gNewWithStr(String, "Hello"); r = gEqual(x, "Hello"); /* r = 1 */ r = gEqual(x, gNewWithStr(String, "Hello")); /* r = 1 */ r = gEqual(x, "World"); /* r = 0 */ |
See also: Compare::String
val = gHash(i); object i; int val; |
This method is used by the generic container classes to obtain hash
values for the object. val
is a hash value between 0 and a large
integer value.
See also: Compare::String
i = gJustifyCenter(i); object i; |
This method is used to center justify the text within a string. The length
of the string is not modified, only the position of the characters within
the string. It is often used in conjunction with Take::String
in
order to format text.
The modified String
instance passed is returned.
Example: object x; x = gNewWithStr(String, "ABD DEF DD "); gJustifyCenter(x); /* x = " ABD DEF DD " */ x = gNewWithStr(String, "ABD DEF"); gJustifyCenter(gTake(x, 14)); /* x = " ABD DEF " */ |
See also: Take::String, JustifyRight::String,
JustifyLeft::String
i = gJustifyLeft(i); object i; |
This method is used to left justify the text within a string. The length
of the string is not modified, only the position of the characters within
the string. It is often used in conjunction with Take::String
in
order to format text.
The modified String
instance passed is returned.
Example: object x; x = gNewWithStr(String, " ABD DEF DD"); gJustifyLeft(x); /* x = "ABD DEF DD " */ x = gNewWithStr(String, "ABD DEF"); gJustifyLeft(gTake(x, 10)); /* x = "ABD DEF " */ |
See also: Take::String, JustifyCenter::String,
JustifyRight::String
i = gJustifyRight(i); object i; |
This method is used to right justify the text within a string. The length
of the string is not modified, only the position of the characters within
the string. It is often used in conjunction with Take::String
in
order to format text.
The modified String
instance passed is returned.
Example: object x; x = gNewWithStr(String, "ABD DEF DD "); gJustifyRight(x); /* x = " ABD DEF DD" */ x = gNewWithStr(String, "ABD DEF"); gJustifyRight(gTake(x, 10)); /* x = " ABD DEF" */ |
See also: Take::String, JustifyCenter::String,
JustifyLeft::String
n = gNumbPieces(i, d); object i; char d; /* delimiter */ int n; /* number of pieces */ |
This method is used to determine the number of sub-strings located in
i
. It is assumed that i
is a string which contains the
delimiter character d
. That delimiter character is used to
logically split string i
into several sub-strings.
Example: object x; int n; x = gNewWithStr(String, "ABD,DEF,DD"); n = gNumbPieces(x, ','); /* n = 3 */ |
See also: Piece::String
r = gPiece(i, d, n); object i; char d; /* delimiter */ int n; /* piece wanted */ object r; /* sub-string */ |
This method is used to create a new string object which will contain a
copy of a sub-string of i
. It is assumed that i
is a
string which contains the delimiter character d
. That delimiter
character is used to logically split string i
into several
sub-strings. n
is used to specify which sub-string is desired.
This method returns a new string object which will contain a copy of the
desired sub-string. A NULL
is returned if n
is greater
than the number of sub-strings in i
.
Example: object x, y; x = gNewWithStr(String, "ABD,DEF,DD"); y = gPiece(x, ',', 0); /* y="ABD" */ y = gPiece(x, ',', 1); /* y="DEF" */ y = gPiece(x, ',', 2); /* y="DD" */ |
See also: NumbPieces::String
sz = gPrintLength(i, ts); object i; int ts; int sz; |
This method is used to obtain the length of the string associated with the instance of the String class passed when it is printed. This method takes into account tabs, backspaces and return characters in its calculations.
ts
is the tab stop size that the method should use.
Note that this is one of the few generics which doesn’t return a Dynace object. It returns an integer.
Example: object x; int sz; x = gNewWithStr(String, "Hello\tWorld\bx"); sz = gPrintLength(x, 8); /* sz = 13 */ |
See also: Size::String
i = gProcess(i); object i; |
This method is used to process a string with embedded escape sequences.
The escape sequences will be processed and converted into the appropriate
control characters. For example "\r"
will be converted in to a return
control character. All the ANSI standard escape sequences are supported.
In addition, "\e"
gets converted into the escape character.
"\^L"
(where L may be any letter - upper or lower case) gets
converted into the corresponding control character, for example
"\^G"
will get converted to the control-G character.
"\dnnn"
works like "\xnnn"
except that nnn
is
treated as a decimal number.
Example: object x; x = gNewWithStr(String, "Hello\\tWorld\\bx"); gProcess(x); /* x will now contain the real control characters */ |
See also: PrintLength::String
i = gRemoveMask(i, mask, text); object i; char *mask; char *text; |
This method is used to remove mask
from text
and set the
resulting value to i
. If NULL
or an empty string
(""
) is passed in to mask
then i
has its string
value changed to text
. If NULL
or an empty string
(""
) is passed in to text
then mask
is removed from
the current string value in i
.
The value returned is the String
instance passed (i
).
Example: object x; char mask = "<(###) ###-####"; x = gNewWithStr(String, "(123) 456-7890"); gRemoveMask(x, mask, NULL); /*x="1234567890" */ gRemoveMask(x, mask, "(987)654-3210"); /*x="9876543210" */ gRemoveMask(x, NULL, "(123) 456-7890");/*x="(123) 456-7890"*/ |
See also: gMaskFunction::String, gSetMaskFiller::String,
gApplyMask::String
r = gSetMaskFiller(i, ch); object i; char ch; char r; |
This method is used to set the character to be used to fill the unused
space in a masked string. This character defaults to be a space but is
frequently set to be the underscore (`_')
character. This method
returns the previous mask filler character.
Example: object x; char r; x = gNewWithStr(String, "1234567"); gApplyMask(x, "<(###) ###-####", NULL); /* x = "( ) 123-4567" */ r = gSetMaskFiller(x, '_'); /* r = ' ' (space) */ gApplyMask(x, "<(###) ###-####", NULL); /* x = "(___) 123-4567" */ |
See also: gMaskFunction::String, gApplyMask::String,
gRemoveMask::String
sz = gSize(i); object i; int sz; |
This method is used to obtain the length of the string associated with the instance of the String class passed.
Note that this is one of the few generics which doesn’t return a Dynace object. It returns an integer.
Example: object x; int sz; x = gNewWithStr(String, "Hello World"); sz = gSize(x); /* sz = 11 */ |
See also: PrintLength::String
s = gStringRepValue(i); object i; object s; |
This method is used to generate an instance of the String
class
which represents the value associated with i
. This is often
used to print or display the value. It is also used by
PrintValue::Object
and indirectly by Print::Object
(two methods useful during the debugging phase of a project)
in order to directly print an object’s value.
Example: object x; object s; x = gNewWithStr(String, "Hello"); s = gStringRepValue(x); /* s represents "Hello" (with quotes) */ |
See also: StringValue::String, PrintValue::Object, Print::Object
val = gStringValue(i); object i; char *val; |
This method is used to obtain the char *
value associated with an
instance of the String class. Note that this is one of the few
generics which doesn’t return a Dynace object. It returns a char * string.
Example: object x; char *val; x = gNewWithStr(String, "Hello World"); val = gStringValue(x); |
See also: New::String, ChangeValue::String
i = gStripCenter(i); object i; |
This method is used to strip off blank characters (space, tab, new line,
carriage return) from both sides of a string. The return value is the
modified String
instance passed.
Example: object x, y; x = gNewWithStr(String, " ABD DEF DD "); gStripCenter(x); /* x = "ABD DEF DD" */ |
See also: StripRight::String, StripLeft::String
i = gStripLeft(i); object i; |
This method is used to strip off blank characters (space, tab, new line,
carriage return) from the left side of a string. The return value is the
modified String
instance passed.
Example: object x, y; x = gNewWithStr(String, " ABD DEF DD "); gStripLeft(x); /* x = "ABD DEF DD " */ |
See also: StripRight::String, StripCenter::String
i = gStripRight(i); object i; |
This method is used to strip off blank characters (space, tab, new line,
carriage return) from the right side of a string. The return value is the
modified String
instance passed.
Example: object x, y; x = gNewWithStr(String, " ABD DEF DD "); gStripRight(x); /* x = " ABD DEF DD" */ |
See also: StripLeft::String, StripCenter::String
so = gSubString(i, beg, num); object i; int beg, num; object so; |
This method is used to create a new instance of the String
class
which is initialized to a copy of a sub-string of instance i
.
beg
indicates the beginning position number of the string to be copied,
index origin zero. num
is the number of characters to copy.
If beg
is negative, beg
will be converted to a beginning point
relative to the end of the string. Therefore, a -1
would indicate
a starting point of the last character in the string and -2
would
indicate a starting point of the second to the last character in the string.
Zero indicates to start at the beginning of the string.
If num
is negative, -num
characters before beg
will be taken.
The new String
instance is returned.
Example: object x, y; x = gNewWithStr(String, "Hello World"); y = gSubString(x, 1, 3); /* y = "ell" */ y = gSubString(x, -5, 5); /* y = "World" */ |
See also: Take::String, Drop::String
i = gTake(i, num); object i; int num; |
This method is used to change the length of the string associated with
the String
instance i
. num
is the new length of
the string. If num
is less than the previous length of the
string, the string will be terminated to the shorter length. If
num
is greater than the previous length, the string will be padded
with spaces until it is num
characters long.
If num
is negative, characters will be taken from the end of the
string and padding will be performed at the beginning of the string.
The modified String
instance passed is returned.
Example: object x, y; x = gNewWithStr(String, "Hello World"); gTake(x, 4); /* x = "Hello" */ x = gNewWithStr(String, "Hello World"); gTake(x, -4); /* x = "orld" */ x = gNewWithStr(String, "ABC"); gTake(x, 5); /* x = "ABC " */ x = gNewWithStr(String, "ABC"); gTake(x, -5); /* x = " ABC" */ |
See also: Drop::String, SubString::String
i = gToLower(i); object i; |
This method is used to convert all the characters in String
instance i
to lower case. Non-alphabetic characters are left
unchanged. The instance passed is returned.
Example: object x; x = gNewWithStr(String, "Hello World"); gToLower(x); /* x = "hello world" */ |
See also: ToUpper::String
i = gToUpper(i); object i; |
This method is used to convert all the characters in String
instance i
to upper case. Non-alphabetic characters are left
unchanged. The instance passed is returned.
Example: object x; x = gNewWithStr(String, "Hello World"); gToUpper(x); /* x = "HELLO WORLD" */ |
See also: ToLower::String
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This class is a subclass of Association
and is used to
represent an association between a C language string and an arbitrary
Dynace object. It performs all the functions as the LookupKey
and ObjectAssociation
classes and is used in conjunction with the
Set
and Dictionary
classes. The purpose of this class is
to provide an efficient mechanism to form a common association.
See the examples included with the Dynace system for an illustration of the
use of the Set
/Dictionary
related classes.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The only class method associated with this class is one needed to create new instances of itself.
i = gNewWithStrObj(StringAssociation, key, val); char *key; object val; /* or NULL */ object i; |
This class method creates instances of the StringAssociation
class. key
is used to initialize the key associated with the
instance created and val
is used to initialize its associated
value. Note that internally key
is copied into an allocated
buffer so that it is all right to reuse the buffer passed to this
method.
The new instance is returned.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The instance methods associated with this class are used to obtain,
change and print the key and value associated with the instance.
Additional functionality, although implemented by this class, is documented
in StringAssociation
’s superclass, Association
. This is done
because of the common interface these methods share with all subclasses
of Association
.
i = gChangeStringKey(i, key); object i; char *key; |
This method is used to change the key associated with instance i
.
key
is the new key. The old key is simply replaced. This method
returns i
.
See also: StringKey::StringAssociation,
ChangeValue::StringAssociation
old = gChangeValue(i, val); object i; object val; /* or NULL */ object old; |
This method is used to change the value associated with an association,
i
, to a value, val
. The old value is simply no longer
associated with the instance. It is not disposed. This method
returns the old value being replaced.
See also: Value::StringAssociation,
ChangeStringKey::StringAssociation
so = gCopy(i); object i, so; |
This method is used to create a new instance of the
StringAssociation
class with the same value as
StringAssociation
i
. Or put more simply, it makes a copy.
The new StringAssociation
instance is returned.
See also: DeepCopy::StringAssociation
so = gDeepCopy(i); object i, so; |
This method is used to create a new instance of the
StringAssociation
class which contains a copy of the
value from the original StringAssociation
. DeepCopy
is
used to create the copy of the value. The new
StringAssociation
instance is returned.
See also: Copy::StringAssociation
r = gDeepDispose(i); object i; object r; /* NULL */ |
This method is used to dispose of a StringAssociation
instance.
It also disposes of the value associated with the instance by the
use of its DeepDispose
method.
The value returned is always NULL
and may be used to null out
the variable which contained the object being disposed in order to
avoid future accidental use.
See also: Dispose::StringAssociation
r = gDispose(i); object i; object r; /* NULL */ |
This method is used to dispose of a StringAssociation
instance.
It does not dispose of its associated value.
The value returned is always NULL
and may be used to null out
the variable which contained the object being disposed in order to
avoid future accidental use.
See also: DeepDispose::StringAssociation
key = gKey(i); object i; object key; |
This method is used to obtain the key associated with instance i
.
See also: StringKey::StringAssociation
key = gStringKey(i); object i; char *key; |
This method is used to obtain the key associated with instance i
.
See also: Key::StringAssociation,
ChangeStringKey::StringAssociation, Value::StringAssociation
s = gStringRepValue(i); object i; object s; |
This method is used to generate an instance of the String
class
which represents the value associated with i
. This is often
used to print or display the value. It is also used by
PrintValue::Object
and indirectly by Print::Object
(two methods useful during the debugging phase of a project)
in order to directly print an object’s value.
See also: PrintValue::Object, Print::Object
val = gValue(i); object i; object val; |
This method is used to obtain the value associated with
i
.
See also: ChangeValue::StringAssociation,
StringKey::StringAssociation
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This class combines the functionality of the Set
and StringAssociation
classes in order to store a collection of
arbitrary key/value pairs.
The difference between this class and the Dictionary
class is
that this class only accepts C language strings as keys. This class
provides an efficient and simple to use means of representing a
commonly needed collection.
This class is a subclass of the Set
class and therefore inherits
all of its functionality.
See the examples included with the Dynace system for an illustration of the
use of the Set
/Dictionary
related classes.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
There are no class methods for this class. It inherits the ability
to create instances of itself through its superclass, Set
.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The instance methods associated with this class are used to add, retrieve
and remove key/value pairs from the Dictionary
. Note that additional
functionality may be obtained through its superclass, Set
.
r = gAddStr(i, key, value); object i; char *key object value; object r; |
This method is used to add a new key/value pair to the StringDictionary
instance (i
). If an object with the same key already exists in
the Dictionary
it will be left as is and AddStr
will return
NULL
. If the key/value objects are added AddStr
will
return the StringAssociation
instance created to represent the
key/value pair passed.
See also: FindStr::StringDictionary, FindValueStr::StringDictionary,
ChangeValueWithStr::StringDictionary,
RemoveStr::StringDictionary
r = gChangeValueWithStr(i, key, value); object i; char *key object value; object r; |
This method is used to change the value associated with an existing
key/value pair to the StringDictionary
instance (i
).
key
represents the identity of the pre-existing key/value
pair and value
represents the new value to be associated with
the key.
Normally, this method changes the value part of the association
and returns the previous value which is not disposed. If
key
doesn’t identify a pre-existing association, this method
simply returns NULL
.
See also: FindStr::StringDictionary, FindValueStr::StringDictionary,
RemoveStr::StringDictionary
r = gDeepDisposeStr(i, key); object i; char *key; object r; |
This method is used to remove and dispose of a key/value pair from a
Dictionary
. If found and removed i
is returned. If key
is not found NULL
is returned.
The value and StringAssociation
used to bind the two are all deep
disposed.
This method is the same as DisposeStr::StringDictionary
.
See also: RemoveStr::StringDictionary
r = gDispose(i); object i; object r; /* NULL */ |
This method is used to dispose of an entire Dictionary
. It does not
dispose of any of the values but does dispose of all the associations
used to represent the pair.
The value returned is always NULL
and may be used to null out
the variable which contained the object being disposed in order to
avoid future accidental use.
See also: RemoveStr::StringDictionary, DeepDispose::Set,
DisposeAllNodes::StringDictionary
i = gDisposeAllNodes(i); object i; |
This method is used to remove all objects in a StringDictionary
instance without disposing of the instance itself. The objects in the
StringDictionary
are simply disassociated from the
StringDictionary
instance and are not disposed.
The value returned is always the instance passed.
See also: DeepDisposeAllNodes::Set, Dispose::StringDictionary
r = gDisposeStr(i, key); object i; char *key; object r; |
This method is used to remove and dispose of a key/value pair from a
Dictionary
. If found and removed i
is returned. If key
is not found NULL
is returned.
The value and StringAssociation
used to bind the two are all deep
disposed.
This method is the same as DeepDisposeStr::StringDictionary
.
See also: RemoveStr::StringDictionary
r = gFindStr(i, key); object i; char *key; object r; |
This method is used to find the instance of the StringAssociation
class which is used to represent the key/value pair stored under
key
in Dictionary
i
. If key
is not found
NULL
is returned.
See also: FindValueStr::StringDictionary
r = gFindAddStr(i, key, value); object i; char *key; object value; object r; |
This method is used to find and return the instance of the
StringAssociation
class used to represent the key/value pair
stored under the key key
. If it is not found a new
StringAssociation
will be added and returned which represent the
key/value pair representing key
and value
.
See also: FindStr::StringDictionary, FindValueStr::StringDictionary
r = gFindValueStr(i, key); object i; char *key; object r; |
This method is used to find the value stored under key
in
Dictionary
i
. If key
is not found NULL
is
returned.
See also: FindStr::StringDictionary
r = gRemoveStr(i, key); object i; char *key; object r; |
This method is used to remove a key/value pair from a Dictionary
.
If found and removed i
is returned. If key
is not found
NULL
is returned.
The value is not disposed, however, the StringAssociation
used to
bind the two is.
See also: DeepDisposeStr::StringDictionary
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The Thread
class gives Dynace the ability to create, manage and
execute multiple threads of execution in a timesharing fashion. See the
manual for a detailed description of threads.
See the examples included with the Dynace system for an illustration of the use of the thread / pipe / semaphore related classes.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The class methods associated with the Thread
class provide a means
to create new instances of the Thread
class. Each instance
represents a unique thread of execution. The class methods also provide
other functionality which is not related to any particular thread, such
as the ability to initialize the threading system.
c = gBlockingGetkey(Thread) int c; |
This method is used to get a key from the keyboard. It does it in a way that allows other threads to continue if there is no key ready. This allows the system to continue to operate while waiting for a user entry.
The thread which calls this method will be placed on hold until a key has been hit. At that time the thread will be enabled and the method will return the key hit.
Only one thread may use this method at a time.
See also: StartThreader
t = gFindStr(Thread, name) char *name; object t; |
This method is used to obtain a thread object from its associated name.
If found it is returned, otherwise NULL
is returned. Note
that the name of the thread which started the thread system is “main”.
If name
is NULL
Find
returns the currently running
thread object.
See also: NewThread::Thread
t = gNewThread(Thread, name, fun, priority, arg, run, autoDispose) char *name; int (*fun)(void *); int priority; void *arg; int run; int autoDispose; object t; |
This class method creates instances of the Thread
class. Each
thread represents a unique thread of execution.
name
is the name of the thread. This name may be used to access
the thread object via its name at a future point. name
may
be null if no particular name is desired.
fun
is the C language function which will implement the process
to be run by the new thread. When fun
is first executed it is
passed the pointer defined by arg
as its only argument. fun
may return an integer result which may be accessed by other threads.
priority
sets the initial priority of the thread. This is a number
between 1 and 30000. The higher the number the greater the priority.
Threads of higher priority (which are ready to run) always run before
any threads of lesser priority. Only ready threads of the same priority
share CPU time. There is a macro named DEFAULT_PRIORITY
which
may be used to create threads which share resources equally. Creating
higher or lower priority threads may be accomplished relative to the
DEFAULT_PRIORITY
macro. Note that all ready threads of
a higher priority must complete before threads of a lower priority will
receive any CPU time.
arg
provides a simple mechanism to pass data to the thread when
it starts. When fun
is started it is passed a single argument
arg
.
run
is a flag to tell the system how to initialize the thread.
If run
is 1 the new thread will be created in a ready-to-run
state. It will be placed on the queue of ready threads and will
automatically start when it gets CPU time. If the thread is started
at a higher priority than the thread which created the new thread
then the current thread will be timed-out and the new thread will
immediately start. If run
is set to 0 the new thread will
be created in a hold state and must be released from this state
in order to start running.
autoDispose
is used to control what happens to the thread
object once the thread completes. If set to 1 the thread will be
automatically disposed when it completes. If set to 0 the thread
will remain in the system until manually disposed. This may
be useful if the return value of the thread is desired after it
has completed. Note that the garbage collector never collects
thread objects. They must be handled manually. Note also that
the way the system was implemented completed threads and threads
on hold take up 0 CPU resources.
The value returned (t
) is the thread object created. If not
kept it may be obtained later by the use of the FindStr::Thread
method. This thread object may be used for many purposes to control
a thread. You may hold, release, change priority, kill or otherwise
query the state of the thread via this object.
Note that the threader must be started prior to the creation of any new
threads. This may be accomplished by the use of the StartThreader
method.
See also: StartThreader, FindStr::Thread
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The instance methods associated with this class are used to manage and query various aspects related to particular threads. Each instance represents a single unique thread.
r = gDeepDispose(t) object t; object r; /* NULL */ |
This method is used to permanently stop the execution of an arbitrary
thread, t
(if it is running) and dispose of it. t
may be
the current thread, in which case the next thread on the queue will
start.
In order to give the thread a return value use Kill::Thread
and then this method.
This method is the same as Dispose::Thread
.
See also: Kill::Thread, Hold::Thread
r = gDispose(t) object t; object r; /* NULL */ |
This method is used to permanently stop the execution of an arbitrary
thread, t
(if it is running) and dispose of it. t
may be
the current thread, in which case the next thread on the queue will
start.
In order to give the thread a return value use Kill::Thread
and then this method.
This method is the same as DeepDispose::Thread
.
The value returned is always NULL
and may be used to null out
the variable which contained the object being disposed in order to
avoid future accidental use.
See also: Kill::Thread, Hold::Thread
t = gChangePriority(t, pri) object t; int pri; |
This method is used to change the priority of thread t
.
Thread t
may be the currently running thread. If thread
t
is changed to a higher priority than the currently running
thread, the currently running will immediately release the CPU to thread
t
.
The priority is a number between 1 and 30000. The higher the number the
greater the priority. Threads of higher priority (which are ready to
run) always run before any threads of lesser priority. Only ready
threads of the same priority share CPU time. There is a macro named
DEFAULT_PRIORITY
which may be used to create threads which share
resources equally. Creating higher or lower priority threads may be
accomplished relative to the DEFAULT_PRIORITY
macro. Note that
all ready threads of a higher priority must complete before
threads of a lower priority will receive any CPU time.
See also: Priority::Thread, NewThread::Thread, State::Thread
t = gHold(t) object t; |
This method is used to place a temporary hold on a thread (t
).
The thread stops execution and waits until released. Threads on hold
take no CPU time. Any number of threads may place any number of holds
on any threads, however, an equal number of releases are required
to release a thread which has been held multiple times. A thread
may put itself on hold. The value returned is the thread passed.
See also: Release::Thread, Kill::Thread
r = gIntValue(t) object t; int r; |
This method is used to obtain the return value of a thread (t
)
which has completed or been killed. If the thread is still running
(or on hold) this method will just return 0.
See also: State::Thread, WaitFor::Thread, Kill::Thread
t = gKill(t, rtn) object t; int rtn; |
This method is used to permanently stop the execution of an arbitrary
thread, t
. Once this method is called on a thread it cannot
be run again. t
may be the current thread, in which case the
next thread on the queue will start. Thread t
is not disposed.
Attempting to Kill
a thread which has already been killed or
completed has no ill effect, rtn
is just ignored.
rtn
represents the return value of the thread, which may be
queried by other threads. Any holds associated with the thread
will be expunged. Thread t
is returned.
Note that killed threads take up no CPU time.
See also: Dispose::Thread, Hold::Thread
nam = gName(t) object t; char *nam; |
This method is used to obtain the name of thread t
.
See also: NewThread::Thread, State::Thread, Priority::Thread
pri = gPriority(t) object t; int pri; |
This method is used to obtain the priority of thread t
.
The priority is a number between 1 and 30000. The higher the number the
greater the priority. Threads of higher priority (which are ready to
run) always run before any threads of lesser priority. Only ready
threads of the same priority share CPU time. There is a macro named
DEFAULT_PRIORITY
which may be used to create threads which share
resources equally. Creating higher or lower priority threads may be
accomplished relative to the DEFAULT_PRIORITY
macro. Note that
all ready threads of a higher priority must complete before
threads of a lower priority will receive any CPU time.
See also: ChangePriority::Thread, NewThread::Thread, State::Thread
t = gRelease(t, yld) object t; int yld; |
This method is used to release a hold placed by the Hold
method on a thread (t
). The thread will not really be released
until the number of calls to Release
is equal to the number
of times Hold
was called on thread t
.
yld
is a flag. It indicates whether the current thread should
yield to the thread being released (if the thread being released has a
higher priority). If yld
is 1 and the thread being released has
a higher priority than the current thread the system will immediately
transfer the CPU to the thread being released. If yld
is set to
0 the current thread will be allowed to complete its time slice. The
value returned is the thread passed.
See also: Hold::Thread
s = gState(t) object t; int s; |
This method is used to obtain the current state of a thread (t
).
The valid states are macros defined in dynl.h
and are defined as
follows:
NEW_THREAD New thread which hasn't started running yet RUNNING_THREAD Thread ready to run HOLD_THREAD Thread placed on hold DONE_THREAD Thread has completed or been killed WAITING_FOR_THREAD Thread waiting for another thread to complete WAITING_FOR_SEMAPHORE Thread waiting for semaphore |
r = gWaitFor(t) object t; int r; |
This method is used to place the current thread on hold until thread
t
completes, gets killed or disposed. At that point the thread
gets released and WaitFor
returns the return value from thread
t
. Note that threads waiting for other threads take up no CPU time.
See also: Kill::Thread, Dispose::Thread, Hold::Thread