SIMPOL Documentation

set

Description

An object of this type provides the ability to store values and objects in a way which can be managed using traditional set operations

Type Tags

None

Object Value

The value of an object of type set is undefined and it is an error to attempt to get or to set it.

set.new()

Description

Creates a new set object.

Prototype

set.new ( string duplicates )

Parameters

ParameterDefault valueType nameDescription
duplicates"allow"string Specifies how the new set will respond to attempts to add more than one copy of a value or object to it. If set to "allow" then more than one copy of a value or object can be stored, and a count of how many copies there are is retained. If set to "ignore" then an attempt to add a second or subseqent copy of a value or object is ignored, with the count of the number of copies of that element being kept at one. If set to "prevent" it is an error to attempt to add a second or subsequent copy of a value or object to the set.

Properties

PropertyTypeDescription
duplicatesstring Specifies how the set responds to attempts to add more than one copy of a value or object to it. If set to "allow" then more than one copy of a value or object can be stored, and a count of how many copies there are is retained. If set to "ignore" then an attempt to add a second or subseqent copy of a value or object is ignored, with the count of the number of copies of that element being kept at one. If set to "prevent" it is an error to attempt to add a second or subsequent copy of a value or object to the set.
typetype Specifies the set type object.

Methods

addobject()

Description

Adds an object to the set, and returns the set object itself.

Prototype

setvar.addobject ( type(*) object, integer count, integer error )

Parameters
ParameterDefault valueType nameDescription
objectNonetype(*) This is the object to be added to the set.
count1integer The number of copies of the object to add to the set.
error.nulinteger Specifies an object that is used to output any error code generated during the execution of the method. This parameter must be an object, not an integer value. If error is not specified or is .nul then any error that occurs during execution will halt the program. If an error object is specified and an error occurs during execution then the error code is output into that object.

addvalue()

Description

Adds a value to the set, and returns the set object itself.

Prototype

setvar.addvalue ( integer|string|blob|boolean|number value, integer count, integer error )

Parameters
ParameterDefault valueType nameDescription
valueNoneinteger|string|blob|boolean|number This is the value to be added to the set. The values .nul and .inf are also permitted.
count1integer The number of copies of the value to add to the set.
error.nulinteger Specifies an object that is used to output any error code generated during the execution of the method. This parameter must be an object, not an integer value. If error is not specified or is .nul then any error that occurs during execution will halt the program. If an error object is specified and an error occurs during execution then the error code is output into that object.

count()

Description

Returns the number of unique elements in the set.

Prototype

setvar.count ()

Parameters

None

difference()

Description

Establishes the difference between the set for which the method is called and the set passed as an argument. The set for which the method is called will then contain only elements (and copies of elements) which previously had been in one set but not both. The set itself is returned.

Prototype

setvar.difference ( set set, integer error )

Parameters
ParameterDefault valueType nameDescription
setNoneset The set that is to be differenced with the set for which the method is called.
error.nulinteger Specifies an object that is used to output any error code generated during the execution of the method. This parameter must be an object, not an integer value. If error is not specified or is .nul then any error that occurs during execution will halt the program. If an error object is specified and an error occurs during execution then the error code is output into that object.

intersect()

Description

Intersects the set with a set passed as an argument. The set for which the method is called will then only contain elements (and copies of elements) that are found in both sets. The set itself is returned.

Prototype

setvar.intersect ( set set, integer error )

Parameters
ParameterDefault valueType nameDescription
setNoneset The set that is to be intersected with the set for which the method is called.
error.nulinteger Specifies an object that is used to output any error code generated during the execution of the method. This parameter must be an object, not an integer value. If error is not specified or is .nul then any error that occurs during execution will halt the program. If an error object is specified and an error occurs during execution then the error code is output into that object.

objectcount()

Description

Returns the number of copies of a specified object in the set. If the object is not in the set then 0 is returned.

Prototype

setvar.objectcount ( type(*) object )

Parameters
ParameterDefault valueType nameDescription
objectNonetype(*) The object to return the number of copies of.

removeobject()

Description

Removes an object from the set, and returns the set object itself.

Prototype

setvar.removeobject ( type(*) object, integer count, integer error )

Parameters
ParameterDefault valueType nameDescription
objectNonetype(*) This is the object to be removed from the set.
count1integer The number of copies of the object to be removed from the set.
error.nulinteger Specifies an object that is used to output any error code generated during the execution of the method. This parameter must be an object, not an integer value. If error is not specified or is .nul then any error that occurs during execution will halt the program. If an error object is specified and an error occurs during execution then the error code is output into that object.

removevalue()

Description

Removes a value from the set, and returns the set object itself.

Prototype

setvar.removevalue ( integer|string|blob|boolean|number value, integer count, integer error )

Parameters
ParameterDefault valueType nameDescription
valueNoneinteger|string|blob|boolean|number This is the value to be removed from the set. The values .nul and .inf are also permitted.
count1integer The number of copies of the value to be removed from the set.
error.nulinteger Specifies an object that is used to output any error code generated during the execution of the method. This parameter must be an object, not an integer value. If error is not specified or is .nul then any error that occurs during execution will halt the program. If an error object is specified and an error occurs during execution then the error code is output into that object.

subtract()

Description

Subtracts a set passed as an argument from the set for which the method is called. The set for which the method is called will then contain only elements (and copies of elements) which were in the set before calling the method, but were not in the set passed as an argument. The set itself is returned.

Prototype

setvar.subtract ( set set, integer error )

Parameters
ParameterDefault valueType nameDescription
setNoneset The the set that is to be subtracted from the set for which the method is called.
error.nulinteger Specifies an object that is used to output any error code generated during the execution of the method. This parameter must be an object, not an integer value. If error is not specified or is .nul then any error that occurs during execution will halt the program. If an error object is specified and an error occurs during execution then the error code is output into that object.

totalcount()

Description

Returns the total number of elements in the set, including all copies of elements.

Prototype

setvar.totalcount ()

Parameters

None

unite()

Description

Unites the set with a set passed as an argument. The set itself is returned.

Prototype

setvar.unite ( set set, integer error )

Parameters
ParameterDefault valueType nameDescription
setNoneset The set that is to be united with the set for which the method is called.
error.nulinteger Specifies an object that is used to output any error code generated during the execution of the method. This parameter must be an object, not an integer value. If error is not specified or is .nul then any error that occurs during execution will halt the program. If an error object is specified and an error occurs during execution then the error code is output into that object.

valuecount()

Description

Returns the number of copies of a specified value in the set. If the value is not in the set then 0 is returned.

Prototype

setvar.valuecount ( integer|string|blob|boolean|number value )

Parameters
ParameterDefault valueType nameDescription
valueNoneinteger|string|blob|boolean|number The value to return the number of copies of. The values .nul and .inf are also permitted.

set[]

Get

Subscripts

An integer value giving the index position of an element in the set.

Description

Retrieves the value or object at the specified index position.

Set

Attempting to set the value is not supported.

Set Reference

Attempting to set a reference to an object is not supported.