diff options
Diffstat (limited to 'tkblt/doc/vector.n')
| -rw-r--r-- | tkblt/doc/vector.n | 1134 |
1 files changed, 0 insertions, 1134 deletions
diff --git a/tkblt/doc/vector.n b/tkblt/doc/vector.n deleted file mode 100644 index fa8bb7e..0000000 --- a/tkblt/doc/vector.n +++ /dev/null @@ -1,1134 +0,0 @@ -'\" -'\" Smithsonian Astrophysical Observatory, Cambridge, MA, USA -'\" This code has been modified under the terms listed below and is made -'\" available under the same terms. -'\" -'\" Copyright 1991-1997 by Lucent Technologies, Inc. -'\" -'\" Permission to use, copy, modify, and distribute this software and its -'\" documentation for any purpose and without fee is hereby granted, provided -'\" that the above copyright notice appear in all copies and that both that the -'\" copyright notice and warranty disclaimer appear in supporting documentation, -'\" and that the names of Lucent Technologies any of their entities not be used -'\" in advertising or publicity pertaining to distribution of the software -'\" without specific, written prior permission. -'\" -'\" Lucent Technologies disclaims all warranties with regard to this software, -'\" including all implied warranties of merchantability and fitness. In no event -'\" shall Lucent Technologies be liable for any special, indirect or -'\" consequential damages or any damages whatsoever resulting from loss of use, -'\" data or profits, whether in an action of contract, negligence or other -'\" tortuous action, arising out of or in connection with the use or performance -'\" of this software. -'\" -'\" Vector command created by George Howlett. -'\" -.TH blt::vector n BLT_VERSION BLT "BLT Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -\fBvector\fR \- Vector data type for Tcl -.SH SYNOPSIS -\fBblt::vector create \fIvecName \fR?\fIvecName\fR...? ?\fIswitches\fR? -.sp -\fBblt::vector destroy \fIvecName \fR?\fIvecName\fR...? -.sp -\fBblt::vector expr \fIexpression\fR -.sp -\fBblt::vector names \fR?\fIpattern\fR...? -.BE -.SH DESCRIPTION -The \fBvector\fR command creates an array of floating point -values. The vector's components can be manipulated in three ways: -through a Tcl array variable, a Tcl command, or the C API. -.SH INTRODUCTION -A vector is an ordered set of real numbers. The components of a -vector are indexed by integers. -.PP -Vectors are common data structures for many applications. For -example, a graph may use two vectors to represent the X-Y -coordinates of the data plotted. The graph will automatically -be redrawn when the vectors are updated or changed. By using vectors, -you can separate -data analysis from the graph widget. This makes it easier, for -example, to add data transformations, such as splines. It's possible -to plot the same data to in multiple graphs, where each graph presents -a different view or scale of the data. -.PP -You could try to use Tcl's associative arrays as vectors. Tcl arrays -are easy to use. You can access individual elements randomly by -specifying the index, or the set the entire array by providing a list -of index and value pairs for each element. The disadvantages of -associative arrays as vectors lie in the fact they are implemented as -hash tables. -.TP 2 -\(bu -There's no implied ordering to the associative arrays. If you used -vectors for plotting, you would want to insure the second component -comes after the first, an so on. This isn't possible since arrays -are actually hash tables. For example, you can't get a range of -values between two indices. Nor can you sort an array. -.TP 2 -\(bu -Arrays consume lots of memory when the number of elements becomes -large (tens of thousands). This is because each element's index and -value are stored as strings in the hash table. -.TP 2 -\(bu -The C programming interface is unwieldy. Normally with vectors, you -would like to view the Tcl array as you do a C array, as an array of -floats or doubles. But with hash tables, you must convert both the -index and value to and from decimal strings, just to access -an element in the array. This makes it cumbersome to perform operations on -the array as a whole. -.PP -The \fBvector\fR command tries to overcome these disadvantages while -still retaining the ease of use of Tcl arrays. The \fBvector\fR -command creates both a new Tcl command and associate array which are -linked to the vector components. You can randomly access vector -components though the elements of array. Not have all indices are -generated for the array, so printing the array (using the \fBparray\fR -procedure) does not print out all the component values. You can use -the Tcl command to access the array as a whole. You can copy, append, -or sort vector using its command. If you need greater performance, or -customized behavior, you can write your own C code to manage vectors. -.SH EXAMPLE -You create vectors using the \fBvector\fR command and its \fBcreate\fR -operation. -.CS -# Create a new vector. -blt::vector create y(50) -.CE -This creates a new vector named \f(CWy\fR. It has fifty components, by -default, initialized to \f(CW0.0\fR. In addition, both a Tcl command -and array variable, both named \f(CWy\fR, are created. You can use -either the command or variable to query or modify components of the -vector. -.CS -# Set the first value. -set y(0) 9.25 -puts "y has [y length] components" -.CE -The array \f(CWy\fR can be used to read or set individual components of -the vector. Vector components are indexed from zero. The array index -must be a number less than the number of components. For example, -it's an error if you try to set the 51st element of \f(CWy\fR. -.CS -# This is an error. The vector only has 50 components. -set y(50) 0.02 -.CE -You can also specify a range of indices using a colon (:) to separate -the first and last indices of the range. -.CS -# Set the first six components of y -set y(0:5) 25.2 -.CE -If you don't include an index, then it will default to the first -and/or last component of the vector. -.CS -# Print out all the components of y -puts "y = $y(:)" -.CE -There are special non-numeric indices. The index \f(CWend\fR, specifies -the last component of the vector. It's an error to use this index if -the vector is empty (length is zero). The index \f(CW++end\fR can be -used to extend the vector by one component and initialize it to a specific -value. You can't read from the array using this index, though. -.CS -# Extend the vector by one component. -set y(++end) 0.02 -.CE -The other special indices are \f(CWmin\fR and \f(CWmax\fR. They return the -current smallest and largest components of the vector. -.CS -# Print the bounds of the vector -puts "min=$y(min) max=$y(max)" -.CE -To delete components from a vector, simply unset the corresponding -array element. In the following example, the first component of -\f(CWy\fR is deleted. All the remaining components of \f(CWy\fR will be -moved down by one index as the length of the vector is reduced by -one. -.CS -# Delete the first component -unset y(0) -puts "new first element is $y(0)" -.CE -The vector's Tcl command can also be used to query or set the vector. -.CS -# Create and set the components of a new vector -blt::vector create x -x set { 0.02 0.04 0.06 0.08 0.10 0.12 0.14 0.16 0.18 0.20 } -.CE -Here we've created a vector \f(CWx\fR without a initial length specification. -In this case, the length is zero. The \fBset\fR operation resets the vector, -extending it and setting values for each new component. -.PP -There are several operations for vectors. The \fBrange\fR operation -lists the components of a vector between two indices. -.CS -# List the components -puts "x = [x range 0 end]" -.CE -You can search for a particular value using the \fBsearch\fR -operation. It returns a list of indices of the components with the -same value. If no component has the same value, it returns \f(CW""\fR. -.CS -# Find the index of the biggest component -set indices [x search $x(max)] -.CE -Other operations copy, append, or sort vectors. You can append -vectors or new values onto an existing vector with the \fBappend\fR -operation. -.CS -# Append assorted vectors and values to x -x append x2 x3 { 2.3 4.5 } x4 -.CE -The \fBsort\fR operation sorts the vector. If any additional vectors -are specified, they are rearranged in the same order as the vector. -For example, you could use it to sort data points represented by x and -y vectors. -.CS -# Sort the data points -x sort y -.CE -The vector \f(CWx\fR is sorted while the components of \f(CWy\fR are -rearranged so that the original x,y coordinate pairs are retained. -.PP -The \fBexpr\fR operation lets you perform arithmetic on vectors. -The result is stored in the vector. -.CS -# Add the two vectors and a scalar -x expr { x + y } -x expr { x * 2 } -.CE -When a vector is modified, resized, or deleted, it may trigger -call-backs to notify the clients of the vector. For example, when a -vector used in the \fBgraph\fR widget is updated, the vector -automatically notifies the widget that it has changed. The graph can -then redrawn itself at the next idle point. By default, the -notification occurs when Tk is next idle. This way you can modify the -vector many times without incurring the penalty of the graph redrawing -itself for each change. You can change this behavior using the -\fBnotify\fR operation. -.CS -# Make vector x notify after every change -x notify always - ... -# Never notify -x notify never - ... -# Force notification now -x notify now -.CE -To delete a vector, use the \fBvector delete\fR command. -Both the vector and its corresponding Tcl command are destroyed. -.CS -# Remove vector x -blt::vector destroy x -.CE -.SH SYNTAX -Vectors are created using the \fBvector create\fR operation. -Th \fBcreate\fR operation can be invoked in one of three forms: -.TP -\fBblt::vector create \fIvecName\fR -This creates a new vector \fIvecName\fR which initially has no components. -.TP -\fBblt::vector create \fIvecName\fR(\fIsize\fR) -This second form creates a new vector which will contain \fIsize\fR -number of components. The components will be indexed starting from -zero (0). The default value for the components is \f(CW0.0\fR. -.TP -\fBblt::vector create \fIvecName\fR(\fIfirst\fR:\fIlast\fR) -The last form creates a new vector of indexed \fIfirst\fR through -\fIlast\fR. \fIFirst\fR and \fIlast\fR can be any integer value -so long as \fIfirst\fR is less than \fIlast\fR. -.PP -Vector names must start with a letter and consist of letters, digits, -or underscores. -.CS -# Error: must start with letter -blt::vector create 1abc -.CE -You can automatically generate vector names using the -"\f(CW#auto\fR" vector name. The \fBcreate\fR operation will generate a -unique vector name. -.CS -set vec [blt::vector create #auto] -puts "$vec has [$vec length] components" -.CE -.SS VECTOR INDICES -Vectors are indexed by integers. You can access the individual vector -components via its array variable or Tcl command. The string -representing the index can be an integer, a numeric expression, a -range, or a special keyword. -.PP -The index must lie within the current range of the vector, otherwise -an an error message is returned. Normally the indices of a vector -are start from 0. But you can use the \fBoffset\fR operation to -change a vector's indices on-the-fly. -.CS -puts $vecName(0) -vecName offset -5 -puts $vecName(-5) -.CE -You can also use numeric expressions as indices. The result -of the expression must be an integer value. -.CS -set n 21 -set vecName($n+3) 50.2 -.CE -The following special non-numeric indices are available: \f(CWmin\fR, \f(CWmax\fR, \f(CWend\fR, and -\f(CW++end\fR. -.CS -puts "min = $vecName($min)" -set vecName(end) -1.2 -.CE -The indices \f(CWmin\fR and \f(CWmax\fR will return the minimum and maximum -values of the vector. The index \f(CWend\fR returns the value of the -last component in the vector. The index \f(CW++end\fR is used to append -new value onto the vector. It automatically extends the vector by -one component and sets its value. -.CS -# Append an new component to the end -set vecName(++end) 3.2 -.CE -A range of indices can be indicated by a colon (:). -.CS -# Set the first six components to 1.0 -set vecName(0:5) 1.0 -.CE -If no index is supplied the first or last component is assumed. -.CS -# Print the values of all the components -puts $vecName(:) -.CE -.SH VECTOR OPERATIONS -.TP -\fBblt::vector create \fIvecName\fR?(\fIsize\fR)?... \fR?\fIswitches\fR? -The \fBcreate\fR operation creates a new vector \fIvecName\fR. Both a -Tcl command and array variable \fIvecName\fR are also created. The -name \fIvecName\fR must be unique, so another Tcl command or array -variable can not already exist in that scope. You can access the -components of the vector using its variable. If you change a value in -the array, or unset an array element, the vector is updated to reflect -the changes. When the variable \fIvecName\fR is unset, the vector and -its Tcl command are also destroyed. -.sp -The vector has optional switches that affect how the vector is created. They -are as follows: -.RS -.TP -\fB\-variable \fIvarName\fR -Specifies the name of a Tcl variable to be mapped to the vector. If -the variable already exists, it is first deleted, then recreated. -If \fIvarName\fR is the empty string, then no variable will be mapped. -You can always map a variable back to the vector using the vector's -\fBvariable\fR operation. -.TP -\fB\-command \fIcmdName\fR -Maps a Tcl command to the vector. The vector can be accessed using -\fIcmdName\fR and one of the vector instance operations. -A Tcl command by that name cannot already exist. -If \fIcmdName\fR is the empty string, no command mapping -will be made. -.TP -\fB\-watchunset \fIboolean\fR -Indicates that the vector should automatically delete itself if -the variable associated with the vector is unset. By default, -the vector will not be deleted. This is different from previous -releases. Set \fIboolean\fR to "true" to get the old behavior. -.RE -.TP -\fBblt::vector destroy \fIvecName\fR \fR?\fIvecName...\fR? -Deletes one or more vectors. Both the Tcl command and array variable -are removed also. -.TP -\fBblt::vector expr \fIexpression\fR -.RS -All binary operators take vectors as operands (remember that numbers -are treated as one-component vectors). The exact action of binary -operators depends upon the length of the second operand. If the -second operand has only one component, then each element of the first -vector operand is computed by that value. For example, the expression -"x * 2" multiples all elements of the vector x by 2. If the second -operand has more than one component, both operands must be the same -length. Each pair of corresponding elements are computed. So "x + y" -adds the the first components of x and y together, the second, and so on. -.sp -The valid operators are listed below, grouped in decreasing order -of precedence: -.TP 20 -\fB\-\0\0!\fR -Unary minus and logical NOT. The unary minus flips the sign of each -component in the vector. The logical not operator returns a vector of -whose values are 0.0 or 1.0. For each non-zero component 1.0 is returned, -0.0 otherwise. -.TP 20 -\fB^\fR -Exponentiation. -.TP 20 -\fB*\0\0/\0\0%\fR -Multiply, divide, remainder. -.TP 20 -\fB+\0\0\-\fR -Add and subtract. -.TP 20 -\fB<<\0\0>>\fR -Left and right shift. Circularly shifts the values of the vector -(not implemented yet). -.TP 20 -\fB<\0\0>\0\0<=\0\0>=\fR -Boolean less, greater, less than or equal, and greater than or equal. -Each operator returns a vector of ones and zeros. If the condition is true, -1.0 is the component value, 0.0 otherwise. -.TP 20 -\fB==\0\0!=\fR -Boolean equal and not equal. -Each operator returns a vector of ones and zeros. If the condition is true, -1.0 is the component value, 0.0 otherwise. -.TP 20 -\fB|\fR -Bit-wise OR. (Not implemented). -.TP 20 -\fB&&\fR -Logical AND. Produces a 1 result if both operands are non-zero, 0 otherwise. -.TP 20 -\fB||\fR -Logical OR. Produces a 0 result if both operands are zero, 1 otherwise. -.TP 20 -\fIx\fB?\fIy\fB:\fIz\fR -If-then-else, as in C. (Not implemented yet). -.LP -See the C manual for more details on the results produced by each -operator. All of the binary operators group left-to-right within the -same precedence level. -.sp -Several mathematical functions are supported for vectors. Each of -the following functions invokes the math library function of the same name; -see the manual entries for the library functions for details on what -they do. The operation is applied to all elements of the vector -returning the results. -.CS -.ta 2c 4c 6c -\fBacos\fR \fBcos\fR \fBhypot\fR \fBsinh\fR -\fBasin\fR \fBcosh\fR \fBlog\fR \fBsqrt\fR -\fBatan\fR \fBexp\fR \fBlog10\fR \fBtan\fR -\fBceil\fR \fBfloor\fR \fBsin\fR \fBtanh\fR -.sp -.CE -Additional functions are: -.TP 1i -\fBabs\fR -Returns the absolute value of each component. -.TP 1i -\fBrandom\fR -Returns a vector of non-negative values uniformly distributed -between [0.0, 1.0) using \fIdrand48\fR. -The seed comes from the internal clock of the machine or may be -set manual with the srandom function. -.TP 1i -\fBround\fR -Rounds each component of the vector. -.TP 1i -\fBsrandom\fR -Initializes the random number generator using \fIsrand48\fR. -The high order 32-bits are set using the integral portion of the first -vector component. All other components are ignored. The low order 16-bits -are set to an arbitrary value. -.PP -The following functions return a single value. -.TP 1i -\fBadev\fR -Returns the average deviation (defined as the sum of the absolute values -of the differences between component and the mean, divided by the length -of the vector). -.TP 1i -\fBkurtosis\fR -Returns the degree of peakedness (fourth moment) of the vector. -.TP 1i -\fBlength\fR -Returns the number of components in the vector. -.TP 1i -\fBmax\fR -Returns the vector's maximum value. -.TP 1i -\fBmean\fR -Returns the mean value of the vector. -.TP 1i -\fBmedian\fR -Returns the median of the vector. -.TP 1i -\fBmin\fR -Returns the vector's minimum value. -.TP 1i -\fBq1\fR -Returns the first quartile of the vector. -.TP 1i -\fBq3\fR -Returns the third quartile of the vector. -.TP 1i -\fBprod\fR -Returns the product of the components. -.TP 1i -\fBsdev\fR -Returns the standard deviation (defined as the square root of the variance) -of the vector. -.TP 1i -\fBskew\fR -Returns the skewness (or third moment) of the vector. This characterizes -the degree of asymmetry of the vector about the mean. -.TP 1i -\fBsum\fR -Returns the sum of the components. -.TP 1i -\fBvar\fR -Returns the variance of the vector. The sum of the squared differences -between each component and the mean is computed. The variance is -the sum divided by the length of the vector minus 1. -.PP -The last set returns a vector of the same length as the argument. -.TP 1i -\fBnorm\fR -Scales the values of the vector to lie in the range [0.0..1.0]. -.TP 1i -\fBsort\fR -Returns the vector components sorted in ascending order. -.RE -.TP -\fBvector names \fR?\fIpattern\fR? -.SH INSTANCE OPERATIONS -You can also use the vector's Tcl command to query or modify it. The -general form is -.DS -\fIvecName \fIoperation\fR \fR?\fIarg\fR?... -.DE -Both \fIoperation\fR and its arguments determine the exact behavior of -the command. The operations available for vectors are listed below. -.TP -\fIvecName \fBappend\fR \fIitem\fR ?\fIitem\fR?... -Appends the component values from \fIitem\fR to \fIvecName\fR. -\fIItem\fR can be either the name of a vector or a list of numeric -values. -.TP -\fIvecName \fBbinread\fR \fIchannel\fR ?\fIlength\fR? ?\fIswitches\fR? -Reads binary values from a Tcl channel. Values are either appended -to the end of the vector or placed at a given index (using the -\fB\-at\fR option), overwriting existing values. Data is read until EOF -is found on the channel or a specified number of values \fIlength\fR -are read (note that this is not necessarily the same as the number of -bytes). The following switches are supported: -.RS -.TP -\fB\-swap\fR -Swap bytes and words. The default endian is the host machine. -.TP -\fB\-at \fIindex\fR -New values will start at vector index \fIindex\fR. This will -overwrite any current values. -.TP -\fB\-format\fR \fIformat\fR -Specifies the format of the data. \fIFormat\fR can be one of the -following: "i1", "i2", "i4", "i8", "u1, "u2", "u4", "u8", "r4", -"r8", or "r16". The number indicates the number of bytes -required for each value. The letter indicates the type: "i" for signed, -"u" for unsigned, "r" or real. The default format is "r16". -.RE -.TP -\fIvecName \fBclear\fR -Clears the element indices from the array variable associated with -\fIvecName\fR. This doesn't affect the components of the vector. By -default, the number of entries in the Tcl array doesn't match the -number of components in the vector. This is because its too expensive -to maintain decimal strings for both the index and value for each -component. Instead, the index and value are saved only when you read -or write an element with a new index. This command removes the index -and value strings from the array. This is useful when the vector is -large. -.TP -\fIvecName \fBdelete\fR \fIindex\fR ?\fIindex\fR?... -Deletes the \fIindex\fRth component from the vector \fIvecName\fR. -\fIIndex\fR is the index of the element to be deleted. This is the -same as unsetting the array variable element \fIindex\fR. The vector -is compacted after all the indices have been deleted. -.TP -\fIvecName \fBdup\fR \fIdestName\fR -Copies \fIvecName\fR to \fIdestName\fR. \fIDestName\fR is the name of a -destination vector. If a vector \fIdestName\fR already exists, it is -overwritten with the components of \fIvecName\fR. Otherwise a -new vector is created. -.TP -\fIvecName \fBexpr\fR \fIexpression\fR -Computes the expression and resets the values of the vector accordingly. -Both scalar and vector math operations are allowed. All values in -expressions are either real numbers or names of vectors. All numbers -are treated as one component vectors. -.TP -\fIvecName \fBlength\fR ?\fInewSize\fR? -Queries or resets the number of components in \fIvecName\fR. -\fINewSize\fR is a number specifying the new size of the vector. If -\fInewSize\fR is smaller than the current size of \fIvecName\fR, -\fIvecName\fR is truncated. If \fInewSize\fR is greater, the vector -is extended and the new components are initialized to \f(CW0.0\fR. If -no \fInewSize\fR argument is present, the current length of the vector -is returned. -.TP -\fIvecName \fBmerge\fR \fIsrcName\fR ?\fIsrcName\fR?... -Merges the named vectors into a single vector. The resulting -vector is formed by merging the components of each source vector -one index at a time. -.TP -\fIvecName \fBnotify\fR \fIkeyword\fR -Controls how vector clients are notified of changes to the vector. -The exact behavior is determined by \fIkeyword\fR. -.RS -.TP 0.75i -\f(CWalways\fR -Indicates that clients are to be notified immediately whenever the -vector is updated. -.TP -\f(CWnever\fR -Indicates that no clients are to be notified. -.TP -\f(CWwhenidle\fR -Indicates that clients are to be notified at the next idle point -whenever the vector is updated. -.TP -\f(CWnow\fR -If any client notifications is currently pending, they are notified -immediately. -.TP -\f(CWcancel\fR -Cancels pending notifications of clients using the vector. -.TP -\f(CWpending\fR -Returns \f(CW1\fR if a client notification is pending, and \f(CW0\fR otherwise. -.RE -.TP -\fIvecName \fBoffset\fR ?\fIvalue\fR? -Shifts the indices of the vector by the amount specified by \fIvalue\fR. -\fIValue\fR is an integer number. If no \fIvalue\fR argument is -given, the current offset is returned. -.TP -\fIvecName \fBpopulate\fR \fIdestName\fR ?\fIdensity\fR? -Creates a vector \fIdestName\fR which is a superset of \fIvecName\fR. -\fIDestName\fR will include all the components of \fIvecName\fR, in -addition the interval between each of the original components will -contain a \fIdensity\fR number of new components, whose values are -evenly distributed between the original components values. This is -useful for generating abscissas to be interpolated along a spline. -.TP -\fIvecName \fBrange\fR \fIfirstIndex\fR ?\fIlastIndex\fR?... -Returns a list of numeric values representing the vector components -between two indices. Both \fIfirstIndex\fR and \fIlastIndex\fR are -indices representing the range of components to be returned. If -\fIlastIndex\fR is less than \fIfirstIndex\fR, the components are -listed in reverse order. -.TP -\fIvecName \fBsearch\fR \fIvalue\fR ?\fIvalue\fR? -Searches for a value or range of values among the components of -\fIvecName\fR. If one \fIvalue\fR argument is given, a list of -indices of the components which equal \fIvalue\fR is returned. If a -second \fIvalue\fR is also provided, then the indices of all -components which lie within the range of the two values are returned. -If no components are found, then \f(CW""\fR is returned. -.TP -\fIvecName \fBset\fR \fIitem\fR -Resets the components of the vector to \fIitem\fR. \fIItem\fR can -be either a list of numeric expressions or another vector. -.TP -\fIvecName \fBseq\fR \fIstart\fR ?\fIfinish\fR? ?\fIstep\fR? -Generates a sequence of values starting with the value \fIstart\fR. -\fIFinish\fR indicates the terminating value of the sequence. -The vector is automatically resized to contain just the sequence. -If three arguments are present, \fIstep\fR designates the interval. -.sp -With only two arguments (no \fIfinish\fR argument), the sequence will -continue until the vector is filled. With one argument, the interval -defaults to 1.0. -.TP -\fIvecName \fBsort\fR ?\fB-reverse\fR? ?\fIargName\fR?... -Sorts the vector \fIvecName\fR in increasing order. If the -\fB-reverse\fR flag is present, the vector is sorted in decreasing -order. If other arguments \fIargName\fR are present, they are the -names of vectors which will be rearranged in the same manner as -\fIvecName\fR. Each vector must be the same length as \fIvecName\fR. -You could use this to sort the x vector of a graph, while still -retaining the same x,y coordinate pairs in a y vector. -.TP -\fIvecName \fBvariable\fR \fIvarName\fR -Maps a Tcl variable to the vector, creating another means for -accessing the vector. The variable \fIvarName\fR can't already -exist. This overrides any current variable mapping the vector -may have. -.RE -.SH C LANGUAGE API -You can create, modify, and destroy vectors from C code, using -library routines. -You need to include the header file \f(CWblt.h\fR. It contains the -definition of the structure \fBBlt_Vector\fR, which represents the -vector. It appears below. -.CS -\fRtypedef struct { - double *\fIvalueArr\fR; - int \fInumValues\fR; - int \fIarraySize\fR; - double \fImin\fR, \fImax\fR; -} \fBBlt_Vector\fR; -.CE -The field \fIvalueArr\fR points to memory holding the vector -components. The components are stored in a double precision array, -whose size size is represented by \fIarraySize\fR. \fINumValues\fR is -the length of vector. The size of the array is always equal to or -larger than the length of the vector. \fIMin\fR and \fImax\fR are -minimum and maximum component values. -.SH LIBRARY ROUTINES -The following routines are available from C to manage vectors. -Vectors are identified by the vector name. -.PP -\fBBlt_CreateVector\fR -.RS .25i -.TP 1i -Synopsis: -.CS -int \fBBlt_CreateVector\fR (\fIinterp\fR, \fIvecName\fR, \fIlength\fR, \fIvecPtrPtr\fR) -.RS 1.25i -Tcl_Interp *\fIinterp\fR; -char *\fIvecName\fR; -int \fIlength\fR; -Blt_Vector **\fIvecPtrPtr\fR; -.RE -.CE -.TP -Description: -Creates a new vector \fIvecName\fR\fR with a length of \fIlength\fR. -\fBBlt_CreateVector\fR creates both a new Tcl command and array -variable \fIvecName\fR. Neither a command nor variable named -\fIvecName\fR can already exist. A pointer to the vector is -placed into \fIvecPtrPtr\fR. -.TP -Results: -Returns \f(CWTCL_OK\fR if the vector is successfully created. If -\fIlength\fR is negative, a Tcl variable or command \fIvecName\fR -already exists, or memory cannot be allocated for the vector, then -\f(CWTCL_ERROR\fR is returned and \fIinterp->result\fR will contain an -error message. -.RE -.sp -.PP -\fBBlt_DeleteVectorByName\fR -.RS .25i -.TP 1i -Synopsis: -.CS -int \fBBlt_DeleteVectorByName\fR (\fIinterp\fR, \fIvecName\fR) -.RS 1.25i -Tcl_Interp *\fIinterp\fR; -char *\fIvecName\fR; -.RE -.CE -.TP 1i -Description: -Removes the vector \fIvecName\fR. \fIVecName\fR is the name of a vector -which must already exist. Both the Tcl command and array variable -\fIvecName\fR are destroyed. All clients of the vector will be notified -immediately that the vector has been destroyed. -.TP -Results: -Returns \f(CWTCL_OK\fR if the vector is successfully deleted. If -\fIvecName\fR is not the name a vector, then \f(CWTCL_ERROR\fR is returned -and \fIinterp->result\fR will contain an error message. -.RE -.sp -.PP -\fBBlt_DeleteVector\fR -.RS .25i -.TP 1i -Synopsis: -.CS -int \fBBlt_DeleteVector\fR (\fIvecPtr\fR) -.RS 1.25i -Blt_Vector *\fIvecPtr\fR; -.RE -.CE -.TP 1i -Description: -Removes the vector pointed to by \fIvecPtr\fR. \fIVecPtr\fR is a -pointer to a vector, typically set by \fBBlt_GetVector\fR or -\fBBlt_CreateVector\fR. Both the Tcl command and array variable of -the vector are destroyed. All clients of the vector will be notified -immediately that the vector has been destroyed. -.TP -Results: -Returns \f(CWTCL_OK\fR if the vector is successfully deleted. If -\fIvecName\fR is not the name a vector, then \f(CWTCL_ERROR\fR is returned -and \fIinterp->result\fR will contain an error message. -.RE -.sp -.PP -\fBBlt_GetVector\fR -.RS .25i -.TP 1i -Synopsis: -.CS -int \fBBlt_GetVector\fR (\fIinterp\fR, \fIvecName\fR, \fIvecPtrPtr\fR) -.RS 1.25i -Tcl_Interp *\fIinterp\fR; -char *\fIvecName\fR; -Blt_Vector **\fIvecPtrPtr\fR; -.RE -.CE -.TP 1i -Description: -Retrieves the vector \fIvecName\fR. \fIVecName\fR is the name of a -vector which must already exist. \fIVecPtrPtr\fR will point be set to -the address of the vector. -.TP -Results: -Returns \f(CWTCL_OK\fR if the vector is successfully retrieved. If -\fIvecName\fR is not the name of a vector, then \f(CWTCL_ERROR\fR is -returned and \fIinterp->result\fR will contain an error message. -.RE -.sp -.PP -\fBBlt_ResetVector\fR -.PP -.RS .25i -.TP 1i -Synopsis: -.CS -int \fBBlt_ResetVector\fR (\fIvecPtr\fR, \fIdataArr\fR, - \fInumValues\fR, \fIarraySize\fR, \fIfreeProc\fR) -.RS 1.25i -Blt_Vector *\fIvecPtr\fR; -double *\fIdataArr\fR; -int *\fInumValues\fR; -int *\fIarraySize\fR; -Tcl_FreeProc *\fIfreeProc\fR; -.RE -.CE -.TP -Description: -Resets the components of the vector pointed to by \fIvecPtr\fR. -Calling \fBBlt_ResetVector\fR will trigger the vector to dispatch -notifications to its clients. \fIDataArr\fR is the array of doubles -which represents the vector data. \fINumValues\fR is the number of -elements in the array. \fIArraySize\fR is the actual size of the array -(the array may be bigger than the number of values stored in -it). \fIFreeProc\fP indicates how the storage for the vector component -array (\fIdataArr\fR) was allocated. It is used to determine how to -reallocate memory when the vector is resized or destroyed. It must be -\f(CWTCL_DYNAMIC\fR, \f(CWTCL_STATIC\fR, \f(CWTCL_VOLATILE\fR, or a pointer -to a function to free the memory allocated for the vector array. If -\fIfreeProc\fR is \f(CWTCL_VOLATILE\fR, it indicates that \fIdataArr\fR -must be copied and saved. If \fIfreeProc\fR is \f(CWTCL_DYNAMIC\fR, it -indicates that \fIdataArr\fR was dynamically allocated and that Tcl -should free \fIdataArr\fR if necessary. \f(CWStatic\fR indicates that -nothing should be done to release storage for \fIdataArr\fR. -.TP -Results: -Returns \f(CWTCL_OK\fR if the vector is successfully resized. If -\fInewSize\fR is negative, a vector \fIvecName\fR does not exist, or -memory cannot be allocated for the vector, then \f(CWTCL_ERROR\fR is -returned and \fIinterp->result\fR will contain an error message. -.RE -.sp -.PP -\fBBlt_ResizeVector\fR -.RS .25i -.TP 1i -Synopsis: -.CS -int \fBBlt_ResizeVector\fR (\fIvecPtr\fR, \fInewSize\fR) -.RS 1.25i -Blt_Vector *\fIvecPtr\fR; -int \fInewSize\fR; -.RE -.CE -.TP -Description: -Resets the length of the vector pointed to by \fIvecPtr\fR to -\fInewSize\fR. If \fInewSize\fR is smaller than the current size of -the vector, it is truncated. If \fInewSize\fR is greater, the vector -is extended and the new components are initialized to \f(CW0.0\fR. -Calling \fBBlt_ResetVector\fR will trigger the vector to dispatch -notifications. -.TP -Results: -Returns \f(CWTCL_OK\fR if the vector is successfully resized. If -\fInewSize\fR is negative or memory can not be allocated for the vector, -then \f(CWTCL_ERROR\fR is returned and \fIinterp->result\fR will contain -an error message. -.sp -.PP -\fBBlt_VectorExists\fR -.RS .25i -.TP 1i -Synopsis: -.CS -int \fBBlt_VectorExists\fR (\fIinterp\fR, \fIvecName\fR) -.RS 1.25i -Tcl_Interp *\fIinterp\fR; -char *\fIvecName\fR; -.RE -.CE -.TP -Description: -Indicates if a vector named \fIvecName\fR exists in \fIinterp\fR. -.TP -Results: -Returns \f(CW1\fR if a vector \fIvecName\fR exists and \f(CW0\fR otherwise. -.RE -.sp -.PP -If your application needs to be notified when a vector changes, it can -allocate a unique \fIclient identifier\fR for itself. Using this -identifier, you can then register a call-back to be made whenever the -vector is updated or destroyed. By default, the call-backs are made at -the next idle point. This can be changed to occur at the time the -vector is modified. An application can allocate more than one -identifier for any vector. When the client application is done with -the vector, it should free the identifier. -.PP -The call-back routine must of the following type. -.CS -.RS -.sp -typedef void (\fBBlt_VectorChangedProc\fR) (Tcl_Interp *\fIinterp\fR, -.RS .25i -ClientData \fIclientData\fR, Blt_VectorNotify \fInotify\fR); -.RE -.sp -.RE -.CE -.fi -\fIClientData\fR is passed to this routine whenever it is called. You -can use this to pass information to the call-back. The \fInotify\fR -argument indicates whether the vector has been updated of destroyed. It -is an enumerated type. -.CS -.RS -.sp -typedef enum { - \f(CWBLT_VECTOR_NOTIFY_UPDATE\fR=1, - \f(CWBLT_VECTOR_NOTIFY_DESTROY\fR=2 -} \fBBlt_VectorNotify\fR; -.sp -.RE -.CE -.PP -\fBBlt_AllocVectorId\fR -.RS .25i -.TP 1i -Synopsis: -.CS -Blt_VectorId \fBBlt_AllocVectorId\fR (\fIinterp\fR, \fIvecName\fR) -.RS 1.25i -Tcl_Interp *\fIinterp\fR; -char *\fIvecName\fR; -.RE -.CE -.TP -Description: -Allocates an client identifier for with the vector \fIvecName\fR. -This identifier can be used to specify a call-back which is triggered -when the vector is updated or destroyed. -.TP -Results: -Returns a client identifier if successful. If \fIvecName\fR is not -the name of a vector, then \f(CWNULL\fR is returned and -\fIinterp->result\fR will contain an error message. -.RE -.sp -.PP -\fBBlt_GetVectorById\fR -.RS .25i -.TP 1i -Synopsis: -.CS -int \fBBlt_GetVector\fR (\fIinterp\fR, \fIclientId\fR, \fIvecPtrPtr\fR) -.RS 1.25i -Tcl_Interp *\fIinterp\fR; -Blt_VectorId \fIclientId\fR; -Blt_Vector **\fIvecPtrPtr\fR; -.RE -.CE -.TP 1i -Description: -Retrieves the vector used by \fIclientId\fR. \fIClientId\fR is a valid -vector client identifier allocated by \fBBlt_AllocVectorId\fR. -\fIVecPtrPtr\fR will point be set to the address of the vector. -.TP -Results: -Returns \f(CWTCL_OK\fR if the vector is successfully retrieved. -.RE -.sp -.PP -\fBBlt_SetVectorChangedProc\fR -.RS .25i -.TP 1i -Synopsis: -.CS -void \fBBlt_SetVectorChangedProc\fR (\fIclientId\fR, \fIproc\fR, \fIclientData\fR); -.RS 1.25i -Blt_VectorId \fIclientId\fR; -Blt_VectorChangedProc *\fIproc\fR; -ClientData *\fIclientData\fR; -.RE -.CE -.TP -Description: -Specifies a call-back routine to be called whenever the vector -associated with \fIclientId\fR is updated or deleted. \fIProc\fR is a -pointer to call-back routine and must be of the type -\fBBlt_VectorChangedProc\fR. \fIClientData\fR is a one-word value to -be passed to the routine when it is invoked. If \fIproc\fR is -\f(CWNULL\fR, then the client is not notified. -.TP -Results: -The designated call-back procedure will be invoked when the vector is -updated or destroyed. -.RE -.sp -.PP -\fBBlt_FreeVectorId\fR -.RS .25i -.TP 1i -Synopsis: -.CS -void \fBBlt_FreeVectorId\fR (\fIclientId\fR); -.RS 1.25i -Blt_VectorId \fIclientId\fR; -.RE -.CE -.TP -Description: -Frees the client identifier. Memory allocated for the identifier -is released. The client will no longer be notified when the -vector is modified. -.TP -Results: -The designated call-back procedure will be no longer be invoked when -the vector is updated or destroyed. -.RE -.sp -.PP -\fBBlt_NameOfVectorId\fR -.RS .25i -.TP 1i -Synopsis: -.CS -char *\fBBlt_NameOfVectorId\fR (\fIclientId\fR); -.RS 1.25i -Blt_VectorId \fIclientId\fR; -.RE -.CE -.TP -Description: -Retrieves the name of the vector associated with the client identifier -\fIclientId\fR. -.TP -Results: -Returns the name of the vector associated with \fIclientId\fR. If -\fIclientId\fR is not an identifier or the vector has been destroyed, -\f(CWNULL\fR is returned. -.RE -.sp -.PP -\fBBlt_InstallIndexProc\fR -.RS .25i -.TP 1i -Synopsis: -.CS -void \fBBlt_InstallIndexProc\fR (\fIindexName\fR, \fIprocPtr\fR) -.RS 1.25i -char *\fIindexName\fR; -Blt_VectorIndexProc *\fIprocPtr\fR; -.RE -.CE -.TP -Description: -Registers a function to be called to retrieved the index \fIindexName\fR -from the vector's array variable. -.sp -typedef double Blt_VectorIndexProc(Vector *vecPtr); -.sp -The function will be passed a pointer to the vector. The function must -return a double representing the value at the index. -.TP -Results: -The new index is installed into the vector. -.RE -.RE -.SH C API EXAMPLE -The following example opens a file of binary data and stores it in an -array of doubles. The array size is computed from the size of the -file. If the vector "data" exists, calling \fBBlt_VectorExists\fR, -\fBBlt_GetVector\fR is called to get the pointer to the vector. -Otherwise the routine \fBBlt_CreateVector\fR is called to create a new -vector and returns a pointer to it. Just like the Tcl interface, both -a new Tcl command and array variable are created when a new vector is -created. It doesn't make any difference what the initial size of the -vector is since it will be reset shortly. The vector is updated when -\fBlt_ResetVector\fR is called. Blt_ResetVector makes the changes -visible to the Tcl interface and other vector clients (such as a graph -widget). -.sp -.CS -#include <tcl.h> -#include <blt.h> -... -Blt_Vector *vecPtr; -double *newArr; -FILE *f; -struct stat statBuf; -int numBytes, numValues; - -f = fopen("binary.dat", "r"); -fstat(fileno(f), &statBuf); -numBytes = (int)statBuf.st_size; - -/* Allocate an array big enough to hold all the data */ -newArr = (double *)malloc(numBytes); -numValues = numBytes / sizeof(double); -fread((void *)newArr, numValues, sizeof(double), f); -fclose(f); - -if (Blt_VectorExists(interp, "data")) { - if (Blt_GetVector(interp, "data", &vecPtr) != TCL_OK) { - return TCL_ERROR; - } -} else { - if (Blt_CreateVector(interp, "data", 0, &vecPtr) != TCL_OK) { - return TCL_ERROR; - } -} -/* - * Reset the vector. Clients will be notified when Tk is idle. - * TCL_DYNAMIC tells the vector to free the memory allocated - * if it needs to reallocate or destroy the vector. - */ -if (Blt_ResetVector(vecPtr, newArr, numValues, numValues, - TCL_DYNAMIC) != TCL_OK) { - return TCL_ERROR; -} -.CE -.SH "INCOMPATIBILITIES" -In previous versions, if the array variable isn't global -(i.e. local to a Tcl procedure), the vector is automatically -destroyed when the procedure returns. -.CS -proc doit {} { - # Temporary vector x - vector x(10) - set x(9) 2.0 - ... -} -.CE -.PP -This has changed. Variables are not automatically destroyed when -their variable is unset. You can restore the old behavior by -setting the "-watchunset" switch. -.CE -.SH KEYWORDS -vector, graph, widget |