object object
Jump to:
Operation Options Description Arguments
--* -- With no arguments following varName, the contents of the object varName are returned as a TCL list. append* -bygroup Append a list of objects, spec1 ..., to the spec1 -byelement object varName. The appended object specs must ?spec2 ...? elementVec all be compatible with the -objects object -copies varName type. (See object Command Options.) copyVec create -database Create a new empty object varName of type type (type | $obj) database# (see BTCL object Types) or of the same type as -elements an existing object $obj. The tensor and database nElements information is also duplicated from $obj unless -matrix specified by the command options. (See (nRows | object Command Options.) symmetric) nColumns cast* -database Recast the object varName as a new type type type dbHandle (see BTCL object Types). For changing an object ?table? -matrix of type integer to type rid, the table (nRows | argument is required. This operation may also symmetric) be used to change the tensor type of the items. nColumns (See object Command Options.) filter* -bygroup Filter object varName, using a filter pattern specified by the object spec pattern. pattern must specify an object of type boolean or integer. Each item of varName is duplicated by the corresponding item value of pattern number of times (being non-negative or 0 or 1 for a boolean type object). Note: the items in the returned object varName are not grouped. (See object Command Options.) get -bygroup Create a new object varName from items indexed $obj -elements by object spec index from object $obj. If ?index? elementVec index is not given, then $obj is copied. Note: -objects all object indices run from 0 to (number of items - 1). The grouping on varName is taken from the index, if it is provided. (See object Command Options.) group* -unset Return the number of groups in object varName. ?groupName? -set If supplied, an object groupName (type integer) groupSpec is created and contains the grouping -size specification of object varName. (See -close object Command Options and more information on grouping.) info* -- Return a TCL-formatted list containing keyword information stored in object varName, as ?keyword ...? requested by the specified keywords. (See object info Operation Keywords.) print* -- Return a tabulated string that contains all information stored in object varName. range -bygroup Create an object varName from a range of items ?group? -pergroup in object $obj. This range is specified as $obj indices first to last, with step step. step first must be positive and defaults to 1 if not ?last? specified. If last is not specified, only one ?step? value at index first is specified. If last is less than first, the items in varName will be in reverse order relative to those in $obj. first or last may be the keyword end, which means the last item of $obj (at [number of items - 1]). first and last may also be out of range, i.e., less than 0 or greater than end. In this case the result is the same as if the boundary values were used if the items in $obj fall within range, i.e., object var range rng $obj -4 1000 would equate to object var range rng $obj 0 end (if number of items in $obj is < 1000), but object var range rng $obj -2 -1 returns an empty object called var. (See object Command Options.) read** -- Read an object from a file or interprocess channel communication (IPC) channel into varName. ?msgVar? If msgVar is not provided, return the message associated with the IPC header of the incoming object. If end-of-file is detected on the input stream before any part of an object (IPC frame) is read, return an empty string and do not set varName (if it was previously set, it is unset). If msgVar is provided, then the incoming message from the IPC frame is placed in the TCL variable msgVar, and the command returns the number of items in the object just read. If end-of-file is detected, msgVar is set to an empty string, and the command returns -1. Also varName is unset (if it previously existed). select -bygroup Compare items in object spec with items in $obj -nosubdivide object $obj and return an object of indices spec -regexp for the matches to varName relative to $obj. -casesensitive The types of the objects $obj and spec must != match. The default value comparison is >= equality (==), but other comparison tests may <= be specified using the command options. (See > object Command Options.) < -anyof -noneof set* -bygroup Set the values in object varName at indices $obj -elements specified by object spec index to values taken ?index? elementVec sequentially from object $obj. Grouping in -objects object varName is not affected. Unlike the object get operation, index is required unless the -elements option is specified. (See object Command Options.) sort -bygroup Sort the items in object $obj by ascending $obj -nosubdivide value and return an object of indices to -casesensitive varName such that getting the values from $obj -reverse using this result would return the items in -value sorted order. If the -value option is used, the actual sorted values, rather than indices, are returned to varName. (See object Command Options.) write*,** -noflush Write the contents of object varName to a file channel or interprocess communication (IPC) channel ?msgString? channel. channel must be an initialized IPC channel or TCL file handle opened for writing. The IPC message string written is the optional argument msgString if it is provided; otherwise the message with the IPC frame defaults to varName. The -noflush option may be used to defer flushing the output stream after the object is written. Using -noflush can improve performance if a number of objects are to be written in rapid succession.
Jump to Syntax or
DescriptionTCL variables are essentially strings of characters which are used by different commands to represent strings, lists, or numbers. However, since these all require translation by the TCL parser and since TCL arrays are associative, performing many mathematical operations using TCL variables is relatively slow. BTCL objects, often referred to simply as objects, allow data to be stored directly in a binary format and to be manipulated in a vectorized manner.
An object can be thought of as an array of data items of a particular type. Simple object types are numeric types such as integers, doubles, Booleans, etc. Special object types include strings, objects, and rids (row identifiers). (See BTCL Object Types table.) In addition to lists of numbers (scalars), the items in a BTCL object may be tensors, e.g., 3 x 1 coordinate vectors, 4 x 4 transformation matrices, 2 x 2 symmetric (compressed) matrices, etc. BTCL objects may also contain grouping information, which specifies that certain ranges of items are banded together.
In an analogous way to how TCL distinguishes a string as a number, list, etc., BTCL objects are recognized as such only by specific commands. When a BTCL object is created, a coded string is assigned to the object variable, which is used as a reference to the actual object data (stored in binary). Hence, unlike TCL variables, the contents of a BTCL object may not be accessed directly. For example, given a BTCL object variable called obj:
BTCL > echo $obj object#8 BTCL > echo [set obj] object#8 BTCL > echo [object obj] 1.23 3.14159The coded string that a BTCL object contains (object#8 in the example above) is often referred to as the object handle. It is important to remember that the content of an object variable is the object handle and not its actual value, for example:
BTCL > set a [expr $obj * 3] Error: syntax error in expression "object#8 * 3" BTCL > vector a multiply $obj 3 BTCL > echo [object a] 3.69 9.42477Although an object handle is just a string and may be copied to other variables, it is important to note that only the original object variable is attached to the object data. When the object variable is set or unset, the object data are deleted, and the original string value of this variable is no longer a valid object handle. For example:
BTCL > set a $obj BTCL > echo $a: [object a] object#8: 1.23 3.14159 BTCL > unset obj BTCL > echo $a: [object a] Error: object: requires "a" to be the name of an existing object variable
Type C-type Description
boolean -- Integer values 0 (false) or 1 (true). integer^ int Integer values in the range -2147483648 to 2147483647. double^ double Real values in the range -xxxxxxxxxx to yyyyyyyyy. string -- String values, e.g., ``hello''. Contents must be scalar. rid -- Short for row-id: integers representing objects in a specific database. Database information is stored as part of the BTCL object data. Contents must be scalar. object -- Pointers to sub-objects. BTCL objects may recursively contain lists of other object structures (see also object-type objects). char^ char Integer values in range 0 to 255. byte^ char Integer values in range 0 to 255. short short Integer values in range -32768 to 32767. long^ long Integer values. Range is machine dependent. ushort unsigned short Integer values in range 0 to 65535. unsigned^ unsigned Integer values in range 0 to 4294967296. float^ float Real values in the range -xxxxxxxxx to yyyyyyyyy.
Jump to Syntax or
BackgroundThe object command is used to examine or manipulate BTCL objects. The object variable used (first argument) must either exist or be the result of an operation on an existing object. The one exception to this statement is the object create operation, which creates a new empty object of a specified type.
Unlike the vector command, which creates objects of a particular type (Boolean, integer, or double) from values and implicit tensor information in a TCL list, the object command affects only the number, order, or grouping of an object's contents and never the actual values of the contents.
The basic operation of the object command (i.e., with no extra arguments) is analogous to that of the TCL set and BTCL vector commands, in that it returns a TCL list-formatted string of the contents of the existing object variable specified (first argument). This operation is identical to the object info contents operation.
The object print operation is used to view all the relevant information about an object. It also returns a formatted string to TCL. This operation takes no further arguments, and the output is tabulated for display. If you want more specific information, the object info operation can be used to return any information that can be specified by one or more keyword arguments (see the object info Operation Keywords table below). The result string is formatted as a TCL list with information in the same order as the keyword arguments specified.
The object create command is one of the most basic object operations. It is used to create an empty object of a specified type. The argument may be a recognized type keyword, as listed in the object types table above, or an object handle, e.g., $obj. If the latter is true, the result object has the same type and item tensor information as $obj but contains no items or grouping information. If object $obj is of type rid, then database and table information is also cloned. If the argument is a type keyword then the resulting object, varName, has scalar items, i.e., only one element per item. The defaults for database, number of elements, and item tensor information can be superceded using the create operation options. (See object Command Options and information on addressing element items.)
The object append command is used to append items to an existing object. This command may take any number of arguments that are object specifications. A valid object specification is either an object handle to an existing BTCL object, e.g., $obj, or a TCL list that defines values that match the type required for the object operation. If the type is integer, Boolean, or real, then valid vector specification strings are accepted. If the type is rid, then a list of scalar integers is accepted. If the type is string, any TCL list is accepted, such that each list element becomes a new string item, for example:
BTCL > object obj create string
BTCL > object obj append "{first 1st} {second 2nd} {third 3rd}" last
BTCL > echo [object obj print]
type: string
items: 4
elements: 1
groups (2):
"first 1st"
"second 2nd"
"third 3rd"
"last"
The append operation may take the -copies option
followed by an integer object specification containing
non-negative scalar values. (See object Command Options.) The
-copies arguments must have as many items as there are
arguments to the append operation. For example:
BTCL > object o create string
BTCL > object o append -copies {1 1 0 2} xxx $obj yyy zzz
BTCL > echo [object o print]
type: string
items: 7
elements: 1
groups (5):
"xxx"
"first 1st"
"second 2nd"
"third 3rd"
"last"
"zzz"
"zzz"
Notice in these examples that the append operation arguments
become new groups in the resulting object. The results of most
object commands have grouping
information, and the append operation can address item elements (see below). The object get command is used to take items from an existing object to create a new object variable. The first argument must be an object handle to an existing object, e.g., $obj. The second (optional) argument is an object specification specifying a list of non-negative scalar indices, running from 0. This argument specifies which items are to be taken from object obj to create the result and the grouping that the result will have. If this argument is not provided, then the get results in an exact copy of object obj. The get operation can address item elements.
The object set command is used to replace items in an existing object. The first argument is an object specification, and the second is an index object specification. The latter argument specifies which items in object varName are to be set to items taken sequentially from the first argument. For example:
BTCL > object obj set {MIDDLE END} {1 3}
BTCL > echo [object obj print]
type: string
items: 4
elements: 1
groups (2):
"first 1st"
"MIDDLE"
"third 3rd"
"END"
The object set command handles grouping
information and can address item
elements. The object select command compares items in the first argument, which is an object specification, with items in the second argument, which must be an object handle, e.g., $obj. The result, varName, is an object containing indices corresponding to items in object obj, which are equal in value to items in the first argument. The comparison test used can be changed from the default equality by using one of the options: !=, >=, -anyof, etc. (see object Command Options). By default, the comparison test is performed for each item of the first argument to all items in the second argument, and the resulting object is grouped accordingly. For example:
BTCL > object ind select != {MIDDLE END} $obj
BTCL > object obj2 get $obj $ind
BTCL > echo [object obj2 print]
type: string
items: 6
elements: 1
groups (2):
"first 1st"
"third 3rd"
"END"
"first 1st"
"MIDDLE"
"third 3rd"
Notice in this example that the grouping on object obj2 is transferred
from the index argument, $ind, which was the result of the
select operation. The select operation may be performed
for all object types except `object'. For select
operations on string type objects, as in this last example,
-casesensitive or -regexp options may be specified to
allow the comparisons to be made in a case-sensitive manner or to use
regular-expresion strings (in the first argument object
specification).The object sort command is used to produce a sorted list of the items in the first argument, which must be an object handle, e.g., $obj. The default result, varName, is an object containing indices corresponding to the values in object obj taken in ascending-value order. The -value option may be used to return the sorted values back to the object varName, rather than the indices, and the -reverse option may be used to change the sorting operation to produce a result in descending-value order. The -casesensitive option may be used for string type objects to make the sorting procedure case-sensitive. (See object Command Options.) The object sort command can handle grouping information.
The object range command is used to extract a range of items from an object specified by the first argument, $obj. If only one extra argument is provided, then this is an index specifying one item to extract from object obj, to produce the result object varName. If two arguments are provided, the second is an index, which, together with the first index, specifies a range of items to extract. The third argument, if provided, is a positive integer specifying a step value for the range. For example:
BTCL > object obj3 range $obj2 1 end 2
BTCL > echo [object obj3 info groups]
({third 3rd}) ({first 1st} {third 3rd})
Notice in this last example that the keyword end has been used
to specify the last item index. The range operation also allows
the range index values to be out of range. If the first value is
negative, this is equivalent to specifying 0. If the first value is
greater than the effective value of end, then this is
equivalent to specifying end. If the first index value is larger
than the second, then the resulting object will have the items in
reverse order. (See object Command
Operations table above.) Also note in the last example, the grouping in the result (denoted by
parentheses). This is determined by the grouping of the original
items that the range spans. The object filter command is used to alter the number of copies of each item in an object, varName. The argument, pattern, is an integer type object specification or a handle to a object of type boolean. The values of the items in pattern must be non-negative and specify how many copies to create of the corresponding item in $varName. Hence, there must be as many items in pattern as there are in object varName. The result from a filter operation does not have grouping information. For example:
BTCL > object obj filter {1 2 0 1}
BTCL > echo [object obj print]
type: string
items: 4
elements: 1
contents:
"first 1st"
"MIDDLE"
"MIDDLE"
"END"
However, you can perform filtering on a
by-group basis. The object cast command is used to re-cast the type of an object varName. The argument may be a recognized type keyword, as listed in the object types table above, or an object handle, e.g., $obj. Casting may be performed only on numeric object types, although rid type objects may be cast to type integer and vice versa. In this case, the integer type object is considered to contain row numbers, i.e., indices to a particular database table. For conversions from type rid to type integer, all items in the object varName must belong to a single database table and must still exist. For conversions from type integer to type rid, an extra argument is required, which must be the name of an existing table in the default System database. The default database may be superceded by using the -database option. The object cast command may also be used to alter the tensor type of the items in object varName, using the -matrix option, but only if the total elements per item stays the same, e.g., a object whose items are 3 x 2 matrices may be converted to an object whose items are 2 x 3 or 6 x 1 matrices. (See object Command Options and information on elements.)
The object read and object write commands are used to read and write an object varName to a file or interprocess communication (IPC) channel. The first argument, channel, must be an initialized IPC channel or TCL file handle opened for reading or writing, respectively. The second argument, msgVar for read, msgString for write, is optional. For read, this is a variable name into which the IPC header message string is returned. For write, this is an IPC header message string to write with the data to the output stream. write also accepts a -noflush option, which specifies that the output stream should not be flushed after the object has been written. Delaying flushes can improve performance if several objects are to be written in succession. The system I/O buffer can be flushed later by an object write command without the -noflush option or with the standard TCL flush command.
Keyword Description
type Request type information for the specified object. nItems Request the number of items for the specified object. nGroups Request the number of groups for the specified object. nElements Request the number of elements per each item for the specified object. rank Request the rank of the specified object's items: 0 means scalar, 1 means vector, and 2 means matrix. columns Request the number of columns in the specified object's items: 1 means all objects whose items are not matrices. rows Request the number of rows in the specified object's items: equals nElements for vector type objects. symmetry Request the symmetry flag of the specified object: use 1 if symmetric (compacted) matrix, 0 otherwise. database Request the database number for the specified object: equals 0 for non-rid type objects. table Request the table name(s) that the items in the specified object originated from: equals ``< NULL > '' for non-rid type objects. contents Request a list of items contained within the specified object. groups Request a list of groups contained within the specified object.
Options Operation Description Arguments
-set group Specify that the group operation is to set the groupVec grouping on an object to groupVec. -unset group Specify that the group operation is to remove the grouping information from an object. -close group -set Allow groupVec to not group all the items in an object. In this case the remaining items form the last group. -size group Specify that the group operation is to refer to the grouping of an object by group sizes rather than by index bounds. -bygroup append For select and sort, operation is performed for filter each group individually rather than on all an get object's items collectively. For filter, get, range range, and set operations, addressing arguments select refer to an object's groups rather than items. set sort -nosubdivide select For select, the resulting groups are not sort subdivided by the number of items selected for the first argument. For sort, the resulting groups are not subdivided for equivalent values. -pergroup range The range arguments refer to items within each group, rather than to all the items collectively. -elements create For create operations, elementIndex is one value elementIndex get specifying the number of elements per item in the set object created. For get and set operations, elementIndex is a list of element indices within the items of an object which are to be addressed. -matrix cast Specify the tensor dimensions for the resulting (symmetric | create matrix object. nRows and nColumns are numbers nRows) specifying the row and column dimensions. The nColumns keyword symmetric specifies a compacted symmetric matrix of dimension nColumns. -byelement append Specify the mapping of the argument item elements elementIndex to the resulting object's item elements. If elementIndex is non-empty, then each element index of the existing object varName must be specified once only. If elementIndex is empty, then elements are addressed in sequence, i.e., "0 1 2 ...". -objects append Specify that the arguments to the object get operation on an object of type object are to be set considered single items rather than objects containing items. -copies append Integer object copyVec specifies the numbers of copyVec copies of each argument object used for the object append command. copyVec may contain only one value if the -byelement option is also specified. -database cast Specify the database from a database handle dbHandle create dbHandle to override the default System database. -casesensitive select Specify that string comparisons are to be sort performed in a case-sensitive manner. The default operation is case-insensitive. -regexp select Specify that the first object's items are regular expression strings and that string matching should be performed accordingly. != < <= > >= select These options override the default == comparison test for the select operation. -anyof select Override the default == comparison test for the select operation. The result is an index object corresponding to each item value in the 2nd argument that matches (==) any value in the 1st argument. Group subdivision does not occur regardless of existing grouping or other options. -noneof select Similar to select -anyof except that the value matching uses a not equal to (!=) comparison of the values. -value sort Specify that the sort operation is to return sorted values rather than sorted indices to those values. -reverse sort Specify that the sort operation is to sort items in descending-value order rather than ascending-value order. -noflush write Specify that the write operation should not flush the system I/O buffer.
The object group command is used to get, set, or unset the grouping information on an existing object. The basic operation of this command is to return the number of groups in an object as a TCL string. This string is always an integer value of at least 1. A value of 1 indicates that all the items are essentially a single group, and often such an object is referred to has having `no' grouping. An object may have more or fewer groups than the number of its items, since it is possible to have groups that do not contain any items. If an argument is provided, then this is used as a variable name to which an integer type object is returned and which contains the grouping information. For example:
BTCL > echo [object obj3 group grp] 2 BTCL > echo [object grp] 0 1 3Notice here that, although there are only two groups, there are three items in the grouping object, grp. The values are indices to the start of each group and to the outside limit of the previous group. Hence, the first value is always 0, and the last is always equal to the number of items in the object.
The -set option of the group operation allows you to set the grouping of an object explicitly. The -unset option allows you to remove any grouping from an object. For example:
BTCL > vector v "1 2 3 4 5 6 7 8" BTCL > echo [object v group -set "0 3 3 5 8"] 4 BTCL > echo [object v info groups] (1.0 2.0 3.0) () (4.0 5.0) (6.0 7.0 8.0) BTCL > echo [object v group -unset] 1 BTCL > echo [object v info groups] (1.0 2.0 3.0 4.0 5.0 6.0 7.0 8.0)Notice in this example that the number of groups returned is that of the resulting grouping rather than that of the original grouping. Also notice that an empty group was created by specifying the same index twice. The optional argument groupName is not allowed when -set or -unset is specified. It is also illegal for the new grouping object specification to have items in decreasing-value order. The first value must be 0, and the last must be the number of items in the object varName. It is possible, however, to have the last index be less than the number of items in varName if the -close option is specified. In this case the operation proceeds as if the number of items in the object were appended to the end of groupName, for example:
BTCL > object v group -close -set "0 3 3 5" BTCL > echo [object v info groups] (1.0 2.0 3.0) () (4.0 5.0) (6.0 7.0 8.0)The -size option specifies that the object group command is to refer to grouping by group sizes rather than by bounding indices. This applies to both the basic and the -set operations. For example:
BTCL > object v group -size grp BTCL > echo [object grp] 3 0 2 3 BTCL > object v group -size -set "3 0 0 4 1" BTCL > echo [object v info groups] (1.0 2.0 3.0) () () (4.0 5.0 6.0 7.0) (8.0)When setting the grouping to be by sizes, the specification object must be composed of non-negative integers, the values of which must sum to the number of items in the object varName. The values may sum to less than this number if the -close option is also specified.
All other object commands, except for object cast, affect the grouping of the resulting object varName. Most object commands allow the -bygroup option (see object Command Options), which changes the default operation from working on a by-item basis to working on a by-group basis. For example, the filter -bygroup operation uses the pattern argument to duplicate whole groups:
BTCL > object v filter -bygroup "2 0 1 1 0" BTCL > echo [object v info groups] (1.0 2.0 3.0) (1.0 2.0 3.0) () (4.0 5.0 6.0 7.0)Notice in this last example that the filter operation returns the object with grouping information, since the filtering was performed on a by-group basis. This -bygroup behavior applies to all the object commands that would usually use an indexing argument to address items, namely filter, range, get, and set. In these cases the argument must now have a number of items matching the number of groups in an object rather than the number of items. For the set -bygroup operation, items are taken sequentially from the first argument object and used to set the corresponding values of the items in the groups specified by the index argument, for example:
BTCL > vector v2 "3.0 2.0 1.0 4.1 5.1 6.1 7.1 8.1" BTCL > object v set -bygroup $v2 "1 3" BTCL > echo [object v info groups] (1.0 2.0 3.0) (3.0 2.0 1.0) () (4.1 5.1 6.1 7.1)The append -bygroup operation is used to append new items or groups to the end of existing groups in an object rather than appending to the end of that object. For this operation, all the argument objects must contain the same number of either items or groups as object varName has groups. For example:
BTCL > vector v2 "int 1 2 3 4 5 6 7 8" BTCL > object v2 group -size -set "3 2 3" BTCL > echo [object v2 info groups] (1 2 3) (4 5) (6 7 8) BTCL > object v2 append -bygroup $v2 BTCL > echo [object v2 info groups] (1 2 3 1 2 3) (4 5 4 5) (6 7 8 6 7 8) BTCL > object v2 append -bygroup "10 20 30" BTCL > echo [object v2 info groups] (1 2 3 1 2 3 10) (4 5 4 5 20) (6 7 8 6 7 8 30)The select -bygroup operation selects items from the first argument with respect to groups in the second argument and returns the result with grouping, with empty groups where no matches were found. For example:
BTCL > object ind select -bygroup 2.0 $v BTCL > echo [object ind info groups] (1) (4) () () BTCL > object ind select -bygroup "2.0 3.0 2.1 5.1" $v BTCL > echo [object ind info groups] (1) (2) () () () () (4) (3) () () () () () () () (7) BTCL > object v2 get $v $ind BTCL > echo [object v2 info groups] (2.0) (3.0) () () () () (2.0) (3.0) () () () () () () () (5.1)Notice in this example that the first select operation, with only one item in the first argument, produces 4 groups in the result, corresponding to matches in the 4 groups of the second argument. The second select operation, however, returns 16 groups, with the items matched in the order in which they appear in the first argument. This is because, for each item in the first argument, a select is performed against each group of the second argument. When groups are spilt into additional groups in this manner, the process is known as group subdivision. The select operation has the option -nosubdivide, to prevent this process from occurring. For example:
BTCL > object ind select -bygroup -nosubdivide "2.0 3.0 2.1 5.1" $v BTCL > object v2 get $v $ind BTCL > echo [object v2 info groups] (2.0 3.0) (2.0 3.0) () (5.1)The object sort operation also has the options -bygroup and -nosubdivide, which work in an entirely analogous way to how they work for the select operation. A sort operation groups the results so that items having the same values are grouped together. If the -bygroup and -nosubdivide options are used, then the groups are sorted individually and this grouping is retained in the result. Without the -nosubdivide option, the resulting groups are subdivided by items having the same value. For example:
BTCL > object v append "10 20 10" BTCL > object v2 sort -value -bygroup -nosubdivide $v BTCL > echo [object v2 info groups] (1.0 2.0 3.0) (1.0 2.0 3.0) () (4.1 5.1 6.1 7.1) (10.0 10.0 20.0) BTCL > object v2 sort -value -bygroup $v BTCL > echo [object v2 info groups] (1.0) (2.0) (3.0) (1.0) (2.0) (3.0) () (4.1) (5.1) (6.1) (7.1) (10.0 10.0) (20.0)Group subdivision can be very useful when doing multiple select and sort operations.
The object range -bygroup operation simply returns ranges of groups rather than ranges of items from the first object argument. The range operation also has a unique option, -pergroup. This allows the range specified to apply to items in each group. For example:
BTCL > echo [object v info groups] (1.0 2.0 3.0) (3.0 2.0 1.0) () (4.1 5.1 6.1 7.1) (10.0 20.0 10.0) BTCL > object r range -pergroup $v 1 3 2 BTCL > echo [object r info groups] (2.0) (2.0) () (5.1 7.1) (20.0)Notice in this last example that, because of the out-of-range behavior of the range operation, all groups are replaced by their second and fourth items where those items exist. This operation is particularly useful after a sort operation to remove duplicated item values.
The object create operation is the only object operation that can create a new object with an explicit element size. If the -elements option is used, followed by an integer object specification containing one positive value, an empty vector object is created whose items have the specified elements. The -matrix option performs a similar function, but the element size is calculated from the matrix dimension, and the result is an empty matrix object. (See object Command Options.)
Both the object get and object set commands also have the -elements option. In this case the argument that follows the option is a scalar object of type integer specification containing indices representing elements. The elementIndex object may not be empty and may not contain item values less than 0 nor greater than the number of elements in an object (less one). For example, the y component of a coordinate vector would have the index 1. Matrix items are divided by the row dimension. Consider the example below that extracts the (row-2, column-3) element from a 4(rows) x 3(columns) matrix:
BTCL > vector mat "int {{1 2 3} {4 5 6} {7 8 9} {0 0 0}}"
BTCL > echo [object mat print]
type: integer
items: 1
elements: 12
contents:
1 2 3 4 5 6 7 8 9 0 0 0
rank: 2
columns: 3
rows: 4
BTCL > $i = [object mat info columns] * (2 - 1) + (3 - 1) ; echo $i
5
BTCL > object e get -elements $i $mat
BTCL > echo [object e]
6
A slightly more complicated example is setting the
diagonal on a 3 x 3 matrix:
BTCL > vector mat "int {{1 0 0} {0 1 0} {0 0 1}}"
BTCL > object mat set -elements "0 4 8" "{2 3 4}" 0
BTCL > echo [object mat]
{{2 0 0} {0 3 0} {0 0 4}}
Notice in this last example that the first argument ("{2 3 4}") is a
vector specification. This is because with the -elements option
this argument must have at least as many elements as items in
elementIndex. The last argument (0) is always required for the
object set operation, even if object varName contains
only one item. The -byelement option for the object append command is very similar to the -elements option. (See object Command Options.) Unlike with the get and set operations, however, the following object specification, elementIndex, must index all the elements in an item once and once only, but it may also be empty. If elementIndex is empty, it is taken to infer "0 1 2 ... nElements-1". The append -byelement operation is used to append to existing vector or matrix objects using argument objects that may have different numbers of elements per item. For example, this operation may be used to join x and y scalar objects, or an xy vector object, to a z scalar object to form one xyz vector object:
BTCL > vector x "1.1 2.1 3.1"
BTCL > vector y "1.2 2.2 3.2"
BTCL > vector z "1.3 2.3 3.3"
BTCL > object xyz create -elements 3 double
BTCL > object xyz append -byelement {} $x $y $z
BTCL > echo [object xyz]
{1.1 1.2 1.3} {2.1 2.2 2.3} {3.1 3.2 3.3}
BTCL > object xy create -elements 2 double
BTCL > object xy append -byelement {} $x $y
BTCL > object xyz append -byelement {} $xy $z
BTCL > echo [object xyz]
{1.1 1.2 1.3} {2.1 2.2 2.3} {3.1 3.2 3.3} {1.1 1.2 1.3} {2.1 2.2 2.3}
{3.1 3.2 3.3}
Unlike most object append operations, where one object
append command with two arguments may be equivalent to two
commands each with one argument, the arguments following a
-byelement option are taken to specify one collective
argument. Consequently, if the -copies option is used, the
copyVec argument may contain only one item. An example where a
non-empty elementIndex object is used would be appending a y
scalar object to a xz vector object to create a xyz vector object:
BTCL > object xyz create -elements 3 double
BTCL > object xz create -elements 2 double
BTCL > object xz append -byelement {} $x $z
BTCL > echo [object xz]
{1.1 1.3} {2.1 2.3} {3.1 3.3}
BTCL > object xyz append -byelement {1 0 2} $y $xz
BTCL > echo [object xyz]
{1.1 1.2 1.3} {2.1 2.2 2.3} {3.1 3.2 3.3}
Finally, the object cast command, as mentioned above, may be used to re-cast a vector
or matrix object as a matrix object, provided that the number of
elements per item does not change. One use of this is to consider data
read in as a vector object to be a symmetric matrix object
(symmetric meaning to BTCL compacted symmetric), for example:
BTCL > vector sym "int {1 1 0 1 0 0}"
BTCL > object sym cast -matrix symmetric 3 integer
BTCL > echo [object sym]
{{1} {1 0} {1 0 0}}
There is no cast option that allows a matrix
object to be converted into a vector object (mainly due to syntax
problems). However, this can be easily achieved using an object
append -bygroup command, for example:
BTCL > object unsym create -elements 6 integer
BTCL > object unsym append -byelement "" $sym
BTCL > echo [object unsym]
{1 1 0 1 0 0}
With the notable exception of the select and sort operations, all object commands treat object-type objects like any other BTCL object types, for example, the append operation is used to append the items in an object of type object to an existing object of this type. However, this is different from appending an object as an item to an existing object of type object.
The -objects option is supported by the object command operations append, get, and set to allow objects to be appended, extracted, or placed in objects of type object. For example:
BTCL > vector v1 "{1 2 3} {4 5 6}"
BTCL > vector v2 "int 10 11 12"
BTCL > object oa create object
BTCL > object oa append -copies "1 2" -objects $v1 $v2
BTCL > echo [object oa]
{double {{1.0 2.0 3.0} {4.0 5.0 6.0}}} {integer {10 11 12}} {integer
{10 11 12}}
BTCL > echo [object oa print]
type: object
items: 3
elements: 1
groups (3):
{
type: double
items: 2
elements: 3
contents:
1.0 2.0 3.0
4.0 5.0 6.0
}
{
type: integer
items: 3
elements: 1
contents:
10
11
12
}
{
type: integer
items: 3
elements: 1
contents:
10
11
12
}
Notice in this example that echoed outputs are necessarily different
for objects of type object, and that each object appended to object oa
is appended as a new group. The arguments to an append
-objects operation must be object handles rather than general
object specifications. This is because the arguments may be of any
object type, and so the command would not know how to determine the
type of the specification strings. However, the contents of the
argument objects are copied so that, for example, if object v1 or v2
were subsequently unset, object oa would not be affected. These
principles are also true for the object get and object
set operations with the -objects option, as shown in the
following example:
BTCL > object oa set -objects $v1 2
BTCL > echo [object oa]
{double {{1.0 2.0 3.0} {4.0 5.0 6.0}}} {integer {10 11 12}} {double
{{1.0 2.0 3.0} {4.0 5.0 6.0}}}
BTCL > object v3 get -objects $oa 1
BTCL > echo [object v3]
10 11 12
In this last example, since the item to be set or got is a single
object, the last argument (the index object) must contain exactly one
value.
Main
access page 
Advanced-Use access.
List of BTCL commands
molGeom command
output command
Copyright Biosym/MSI