--- /dev/null
+'\"
+'\" 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.
+'\"
+.so man.macros
+.TH vector n BLT_VERSION BLT "BLT Built-In Commands"
+.BS
+'\" Note: do not modify the .SH NAME line immediately below!
+.SH NAME
+vector \- Vector data type for Tcl
+.SH SYNOPSIS
+\fBvector configure \fIoption value ...\fR
+.sp
+\fBvector create \fIvecName \fR?\fIvecName\fR...? ?\fIswitches\fR?
+.sp
+\fBvector destroy \fIvecName \fR?\fIvecName\fR...?
+.sp
+\fBvector expr \fIexpression\fR
+.sp
+\fBvector names \fR?\fIpattern\fR...?
+.sp
+\fBvector op\fR \fIoperation vecName\fR ?\fIarg\fR?...
+.BE
+.SH DESCRIPTION
+The \fBvector\fR command creates a vector 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 simply an ordered set of numbers. The components of a
+vector are real numbers, indexed by counting numbers.
+.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 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.
+vector create y(50)
+.CE
+This creates a new vector named \fBy\fR. It has fifty components, by
+default, initialized to \fB0.0\fR. In addition, both a Tcl command
+and array variable, both named \fBy\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 \fBy\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 \fBy\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 \fBend\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 \fB++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 \fBmin\fR and \fBmax\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
+\fBy\fR is deleted. All the remaining components of \fBy\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
+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 \fBx\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 \fB""\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 \fBx\fR is sorted while the components of \fBy\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
+
+# Set Tcl callback for update of Tktable widget .t.
+x notify callback {.t conf -padx [.t cget -padx]; .t reread}
+
+.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
+vector destroy x
+.CE
+The psuedo vector \fBlast\fR can be used at the end of an
+expression to implement running totals.
+During execution it resolves to the result from the previous
+vector element evaluation.
+.CS
+vector create A(10)
+vector create B(10)
+vector create S(10)
+vector create T(10)
+S expr A+B
+T expr S+last; # Running total
+.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
+\fBvector create \fIvecName\fR
+This creates a new vector \fIvecName\fR which initially has no components.
+.TP
+\fBvector 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 \fB0.0\fR.
+.TP
+\fBvector create \fIvecName\fR(\fIrows,columns\fR)
+This form allows creation of a matrix with the specified columns and
+\fIrows*columns\fR elements.
+See the \fImatrix\fR section for more details.
+.TP
+\fBvector 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
+vector create 1abc
+.CE
+You can automatically generate vector names using the
+"\fB#auto\fR" vector name. The \fBcreate\fR operation will generate a
+unique vector name.
+.CS
+set vec [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
+When \fImatrix numcols\fR is > 1, 2D indexes are supported using
+ROW,COL form.
+.CS
+vecName matrix numcols 3
+puts vecName(0,2)
+.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: \fBmin\fR, \fBmax\fR, \fBend\fR, and
+\fB++end\fR.
+.CS
+puts "min = $vecName($min)"
+set vecName(end) -1.2
+.CE
+The indices \fBmin\fR and \fBmax\fR will return the minimum and maximum
+values of the vector. Also available are: \fBprod\fR, \fBsum\fR,
+and \fBmean\fR.
+The index \fBend\fR returns the value of the
+last component in the vector.
+he index \fBend,0\fR returns the value of the
+last row in column 0 of the vector.
+The index \fB++end\fR is used to append
+new value onto the vector. It automatically extends the vector by
+numcols 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
+\fBvector configure \fI? -flush bool -watchunset bool -oldcreate bool -maxsize int -novariable bool -nocommand bool?\fR
+The \fBconfigure\fR operation sets the default options used
+in creating vectors: these options are global to the interpreter.
+The \fI\-maxsize\fR option, when non-zero, limits creation size.
+The \fI\-oldcreate\fR enable the creation shortcut: \fBvector vec1 vec2 ...\fR.
+See the create command for details on the others.
+By default, these are all disabled or zero.
+.RE
+.TP
+\fBvector create \fIvecName\fR?(\fIsize\fR)?... \fR?\fIswitches\fR?
+The \fBcreate\fR operation creates a new vector \fIvecName\fR. The
+\fIsize\fR may be an integer, a START:END range or ROW,COL (see matrix).
+This creates both a
+Tcl command and array variable called \fIvecName\fR. The
+name \fIvecName\fR must be unique, so another Tcl command or array
+variable can not already exist in the current scope. You may access the
+components of the vector using the 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.
+.TP
+\fB\-flush \fIboolean\fR
+Indicates that the vector should automatically flush the cached
+variable elements which unsets all the elements of the Tcl array
+variable associated with the vector, freeing memory associated
+with the variable. This includes both the hash table and the hash keys.
+The down side is that this effectively flushes the caching of vector
+elements in the array. This means that the subsequent reads
+of the array will require a decimal to string conversion.
+By default, flushing is disabled.
+.RE
+.TP
+\fBvector destroy \fIvecName\fR \fR?\fIvecName...\fR?
+Destroy vectors.
+.TP
+\fBvector 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
+.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
+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.
+.LP
+.sp
+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. All functions take a vector operand.
+If no vector operand is used in the call, the current
+vector is assumed. eg.
+.CS
+vector create aVec
+aVec seq 0 100
+aVec expr {2*abs(aVec)-1}
+aVec length 100
+aVec expr {2*row()}
+vector expr {2*row()} ; # ERROR!
+.CE
+.CS
+.ta 3c 6c 9c
+\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
+.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
+This last set of functions returns a vector of the same length as the argument.
+.TP 1i
+\fBinvert\fR
+Returns vector with elements in reversed order.
+.TP 1i
+\fBnorm\fR
+Scales the values of the vector to lie in the range [0.0..1.0].
+.TP 1i
+\fBrow\fR
+Psuedo function to get the current row.
+.TP 1i
+\fBsort\fR
+Returns the vector components sorted in ascending order.
+.TP 1i
+\fBshift(nVec,N)\fR
+This is the only function taking a second arg.
+It provides a version of \fInvec\fR shifted by N places.
+When N is a scalar or vector with only one element,
+shift fills vacant area with 0. Otherwise the second element of
+\fInVec\fR is used for the fill value.
+One use for this is providing running totals.
+.RE
+.TP
+\fBvector names \fR?\fIpattern\fR?
+Return names of all defined vectors.
+.RE
+.TP
+\fBvector op\fR \fIoperation vecName\fR ?\fIarg\fR?...
+Invoke instance operation. Supported operations are defined in the next section.
+Op is the only way to invoke instance operation sub-commands
+when -command is defined as empty in
+a vector. It also allows writing vector code that is checkable
+by a syntax checkers. eg.
+.CS
+
+vector create v1
+v1 op append {1 2 3}
+v1 op modify 1 2.1
+
+.CE
+.RE
+.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
+Note this is equivalent to the form:
+.DS
+\fBvector op\fR \fIoperation vecName\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 \fB+\fR \fIitem\fR
+\fIvecName \fB-\fR \fIitem\fR
+\fIvecName \fB*\fR \fIitem\fR
+\fIvecName \fB/\fR \fIitem\fR
+Perform binary op and return result as a list.
+.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 \fBbinwrite\fR \fIchannel\fR ?\fIlength\fR? ?\fI\-at index\fR?
+Like \fBbinread\fR, but writes data.
+.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 \fBindex\fR \fIindex\fR ?\fIvalue\fR?...
+Get/set individual vector values. This provides element
+updating when \fI\-variable\fR is set to empty.
+.TP
+\fIvecName \fBinsert\fR \fIindex\fR \fIitem\fR ?\fIitem\fR?...
+Inserts the component values from \fIitem\fR to \fIvecName\fR at
+\fIindex\fR \fIItem\fR can be either the name of a vector or
+a list of numeric values.
+.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 \fB0.0\fR. If
+no \fInewSize\fR argument is present, the current length of the vector
+is returned.
+.TP
+\fIvecName \fBmatrix \fI ...\fR
+Matrix provides a 2D array view into 1D data. It provides indexing operations
+in ROW,COL form making it suitable for use with TkTable.
+Data storage remains unchanged: vectors are still just a single long array.
+For example, here are two ways to create a 3 column by 10 row matrix:
+.CS
+
+vector create aVec(10,3)
+vector create bVec(30)
+bVec matrix numcols 3
+set aVec(0,0) 99
+set bVec(29,2) -99
+aVec append {5 6 7}; # aVec now has 11 rows.
+aVec append 1 2; # Now aVec has 13 rows!
+
+.CE
+Note that data is appended only in increments of numcols.
+Elements 0-2 make up the first row, 3-5 the second, etc.
+Elements will appear only in increments of the column size.
+.RS
+.TP 0.75i
+\fIvecName \fBmatrix copy \fIdstcolumn\fR \fIsrccolumn\fR \fI?srcVec?\fR
+Copy a column of element values
+to column \fIdstcolumn\fR from \fIsrccolumn\fR.
+If vector \fIsrcVec\fR is given, and not the same as \fIvecName\fR, the
+columns numbers must be different.
+If the \fIsrcVec\fR column is longer, \fIvecName\fR will be extended.
+If shorter, remaining destination values are not overwritten.
+.TP
+\fIvecName \fBmatrix delete \fIcolumn\fR.
+Delete elements in a column.
+Note that \fBnumcols\fR, which must be greater than 1, will be decremented.
+.TP
+\fIvecName \fBmatrix get \fIcolumn\fR
+Get the element in a column: this number must be
+less than \fBnumcols\fR.
+Note that \fBnumcols\fR must be non-zero.
+.TP
+\fIvecName \fBmatrix insert \fIcolumn\fR \fI?initvalue?\fR .
+Insert a new column of elements at column (default 0).
+The new column is initialized
+with \fIinitvalue\fR, or \fI0.0\fR if not specified.
+Note that \fBnumcols\fR will be incremented.
+.TP
+\fIvecName \fBmatrix multiply \fIsrcVec\fR ?\fIdstVec\fR?
+Perform matrix multiplication using \fBsrcVec\fR,
+placing results either in \fBdstVec\fR, or returned as a list.
+The numrows of \fIsrcVec\fR must equal numcols in
+\fIvecName\fR. One application for multiply is coordinate transformation.
+.TP
+\fIvecName \fBmatrix numcols \fI?size?\fR
+Get or set the number of columns for a vectors data. Values >1 enable
+array variables to accept 2d matrix indexes.
+For example with a numcols of 10, \fB$vec1(1,2)\fR refers to the
+13th element in the vector. A vectors size is also constrained
+to multiples of numcols, as is it's offset.
+By default, numcols is 1.
+.TP
+\fIvecName \fBmatrix numrows \fI?size?\fR
+Get or set the length of rows in a columns for a vector.
+By default, this is just the \fIvector length/numcols\fR.
+Setting this value simply provides a convenient way to increase or decrease
+the vector size by multiples of \fInumcols\fR.
+.TP
+\fIvecName \fBmatrix set \fIcolumn\fR \fI?valuelist?\fR
+Set value elements in a column: this number must be
+less than \fBnumcols\fR. The \fIvaluelist\fR is a list values.
+If this list is shorter than the column, it's last
+value is used for all remaining columns. The column gets set to
+the values of \fIitem\fR, or \fI0.0\fR by default.
+.TP
+\fIvecName \fBmatrix shift \fIcolumn\fR \fIamount\fR ?\fIstartoffset\fR?
+Shifts the values of a column by integer in\fIamount\fR. A negative
+value shifts upward.
+The \fIstartoffset\fR indicates where to start shifting from.
+.TP
+\fIvecName \fBmatrix sort \fIcolumn\fR \fI?-reverse?\fR
+Sort the vector by the given column.
+.TP
+\fIvecName \fBmatrix transpose\fR
+Transpose all columns with rows in matrix.
+Note that this is a no-op if \fBnumcols\fR is 1. Otherwise,
+numcols will change to \fBvectorLength/numcols\fR.
+.RE
+.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? ?\fIscript\fR?
+Queries or controls how vector clients are notified of changes
+to the vector. Also allows setting a notifier callback.
+The exact behavior is determined by \fIkeyword\fR.
+.RS
+.TP 0.75i
+\fBalways\fR
+Indicates that clients are to be notified immediately whenever the
+vector is updated.
+.TP
+\fBnever\fR
+Indicates that no clients are to be notified.
+.TP
+\fBwhenidle\fR
+Indicates that clients are to be notified at the next idle point
+whenever the vector is updated.
+.TP
+\fBnow\fR
+If any client notifications is currently pending, they are notified
+immediately.
+.TP
+\fBcancel\fR
+Cancels pending notifications of clients using the vector.
+.TP
+\fBpending\fR
+Returns \fB1\fR if a client notification is pending, and \fB0\fR otherwise.
+.TP
+\fBcallback\fR ?\fIscript\fR?
+Query or set a Tcl callback script that is evaluated when a vector is updated.
+.RE
+.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 \fB""\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 \fBsplit\fR \fIdstName\fR ?\fIdstName\fR?...
+Split the vector into a multiple vectors. The resulting
+N vectors each contain the mod-Nth element from source.
+.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 \fBblt.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 \fBTCL_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
+\fBTCL_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 \fBTCL_OK\fR if the vector is successfully deleted. If
+\fIvecName\fR is not the name a vector, then \fBTCL_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 \fBTCL_OK\fR if the vector is successfully deleted. If
+\fIvecName\fR is not the name a vector, then \fBTCL_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 \fBTCL_OK\fR if the vector is successfully retrieved. If
+\fIvecName\fR is not the name of a vector, then \fBTCL_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
+\fBTCL_DYNAMIC\fR, \fBTCL_STATIC\fR, \fBTCL_VOLATILE\fR, or a pointer
+to a function to free the memory allocated for the vector array. If
+\fIfreeProc\fR is \fBTCL_VOLATILE\fR, it indicates that \fIdataArr\fR
+must be copied and saved. If \fIfreeProc\fR is \fBTCL_DYNAMIC\fR, it
+indicates that \fIdataArr\fR was dynamically allocated and that Tcl
+should free \fIdataArr\fR if necessary. \fBStatic\fR indicates that
+nothing should be done to release storage for \fIdataArr\fR.
+.TP
+Results:
+Returns \fBTCL_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 \fBTCL_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 \fB0.0\fR.
+Calling \fBBlt_ResetVector\fR will trigger the vector to dispatch
+notifications.
+.TP
+Results:
+Returns \fBTCL_OK\fR if the vector is successfully resized. If
+\fInewSize\fR is negative or memory can not be allocated for the vector,
+then \fBTCL_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 \fB1\fR if a vector \fIvecName\fR exists and \fB0\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 {
+ \fBBLT_VECTOR_NOTIFY_UPDATE\fR=1,
+ \fBBLT_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 \fBNULL\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 \fBTCL_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
+\fBNULL\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,
+\fBNULL\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
OSDN Git Service
