--- /dev/null
+
+ <!-- manual page source format generated by PolyglotMan v3.0.9, -->
+<!-- available via anonymous ftp from ftp.cs.berkeley.edu:/ucb/people/phelps/tcltk/rman.tar.Z -->
+
+<HTML>
+<HEAD>
+<TITLE>vector(n) manual page</TITLE><!--#include virtual="/man/maninc.html"-->
+</HEAD>
+<BODY bgcolor=white>
+<A HREF="#toc">Table of Contents</A><P>
+
+<H2><A NAME="sect0" HREF="#toc0">Name</A></H2>
+vector - Vector data type for
+Tcl
+<H2><A NAME="sect1" HREF="#toc1">Synopsis</A></H2>
+<B>vector configure <I>option value ...</I></B> <P>
+<B>vector create <I>vecName </I></B>?<I>vecName</I>...?
+?<I>switches</I>? <P>
+<B>vector destroy <I>vecName </I></B>?<I>vecName</I>...? <P>
+<B>vector expr <I>expression</I></B> <P>
+<B>vector
+names </B>?<I>pattern</I>...? <P>
+<B>vector op</B> <I>operation vecName</I> ?<I>arg</I>?...
+<H2><A NAME="sect2" HREF="#toc2">Description</A></H2>
+The <B>vector</B>
+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.
+<H2><A NAME="sect3" HREF="#toc3">Introduction</A></H2>
+A vector is simply an ordered set of numbers.
+The components of a vector are real numbers, indexed by counting numbers.
+<P>
+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. <P>
+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.
+<UL>
+<LI>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. </LI><LI>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. </LI><LI>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. </LI>
+</UL>
+<P>
+The <B>vector</B> command tries to overcome these disadvantages
+while still retaining the ease of use of Tcl arrays. The <B>vector</B> 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 <B>parray</B> 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.
+<H2><A NAME="sect4" HREF="#toc4">Example</A></H2>
+You create vectors using the <B>vector</B> command
+and its <B>create</B> operation. <BR>
+<CODE># Create a new vector. <BR>
+vector create y(50)<BR>
+</CODE>This creates a new vector named y. It has fifty components, by default,
+initialized to 0.0. In addition, both a Tcl command and array variable,
+both named y, are created. You can use either the command or variable
+to query or modify components of the vector. <BR>
+<CODE># Set the first value. <BR>
+set y(0) 9.25<BR>
+puts "y has [y length] components"<BR>
+</CODE>The array y 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 y. <BR>
+<CODE># This is an error. The vector only has 50 components.<BR>
+set y(50) 0.02<BR>
+</CODE>You can also specify a range of indices using a colon (:) to separate the
+first and last indices of the range. <BR>
+<CODE># Set the first six components of y <BR>
+set y(0:5) 25.2<BR>
+</CODE>If you don't include an index, then it will default to the first and/or
+last component of the vector. <BR>
+<CODE># Print out all the components of y <BR>
+puts "y = $y(:)"<BR>
+</CODE>There are special non-numeric indices. The index end, 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 ++end 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. <BR>
+<CODE># Extend the vector by one component.<BR>
+set y(++end) 0.02<BR>
+</CODE>The other special indices are min and max. They return the current
+smallest and largest components of the vector. <BR>
+<CODE># Print the bounds of the vector<BR>
+puts "min=$y(min) max=$y(max)"<BR>
+</CODE>To delete components from a vector, simply unset the corresponding array
+element. In the following example, the first component of y is deleted.
+ All the remaining components of y will be moved down by one index as
+the length of the vector is reduced by one. <BR>
+<CODE># Delete the first component<BR>
+unset y(0)<BR>
+puts "new first element is $y(0)"<BR>
+</CODE>The vector's Tcl command can also be used to query or set the vector. <BR>
+<CODE># Create and set the components of a new vector<BR>
+vector create x<BR>
+x set { 0.02 0.04 0.06 0.08 0.10 0.12 0.14 0.16 0.18 0.20 }<BR>
+</CODE>Here we've created a vector x without a initial length specification. In
+this case, the length is zero. The <B>set</B> operation resets the vector, extending
+it and setting values for each new component. <P>
+There are several operations
+for vectors. The <B>range</B> operation lists the components of a vector between
+two indices. <BR>
+<CODE># List the components <BR>
+puts "x = [x range 0 end]"<BR>
+</CODE>You can search for a particular value using the <B>search</B> operation. It returns
+a list of indices of the components with the same value. If no component
+has the same value, it returns "". <BR>
+<CODE># Find the index of the biggest component<BR>
+set indices [x search $x(max)]<BR>
+</CODE>Other operations copy, append, or sort vectors. You can append vectors
+or new values onto an existing vector with the <B>append</B> operation. <BR>
+<CODE># Append assorted vectors and values to x<BR>
+x append x2 x3 { 2.3 4.5 } x4<BR>
+</CODE>The <B>sort</B> 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. <BR>
+<CODE># Sort the data points<BR>
+x sort y<BR>
+</CODE>The vector x is sorted while the components of y are rearranged so
+that the original x,y coordinate pairs are retained. <P>
+The <B>expr</B> operation
+lets you perform arithmetic on vectors. The result is stored in the vector.
+<BR>
+<CODE># Add the two vectors and a scalar<BR>
+x expr { x + y }<BR>
+x expr { x * 2 }<BR>
+</CODE>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 <B>graph</B> 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 <B>notify</B> operation. <BR>
+<CODE># Make vector x notify after every change<BR>
+x notify always<BR>
+<tt> </tt> <tt> </tt> ...<BR>
+# Never notify<BR>
+x notify never<BR>
+<tt> </tt> <tt> </tt> ...<BR>
+# Force notification now<BR>
+x notify now<BR>
+<P>
+# Set Tcl callback for update of Tktable widget .t.<BR>
+x notify callback {.t conf -padx [.t cget -padx]; .t reread}<BR>
+<P>
+</CODE>To delete a vector, use the <B>vector delete</B> command. Both the vector and
+its corresponding Tcl command are destroyed. <BR>
+<CODE># Remove vector x<BR>
+vector destroy x<BR>
+</CODE>The psuedo vector <B>last</B> 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. <BR>
+<CODE>vector create A(10)<BR>
+vector create B(10)<BR>
+vector create S(10)<BR>
+vector create T(10)<BR>
+S expr A+B<BR>
+T expr S+last; # Running total<BR>
+
+<H2><A NAME="sect5" HREF="#toc5"></CODE>Syntax</A></H2>
+Vectors are created using the <B>vector create</B> operation. Th <B>create</B>
+operation can be invoked in one of three forms:
+<DL>
+
+<DT><B>vector create <I>vecName</I></B> </DT>
+<DD>This
+creates a new vector <I>vecName</I> which initially has no components. </DD>
+
+<DT><B>vector create
+<I>vecName</I></B>(<I>size</I>) </DT>
+<DD>This second form creates a new vector which will contain
+<I>size</I> number of components. The components will be indexed starting from
+zero (0). The default value for the components is 0.0. </DD>
+
+<DT><B>vector create <I>vecName</I></B>(<I>rows,columns</I>)
+</DT>
+<DD>This form allows creation of a matrix with the specified columns and <I>rows*columns</I>
+elements. See the <I>matrix</I> section for more details. </DD>
+
+<DT><B>vector create <I>vecName</I></B>(<I>first</I>:<I>last</I>)
+</DT>
+<DD>The last form creates a new vector of indexed <I>first</I> through <I>last</I>. <I>First</I>
+and <I>last</I> can be any integer value so long as <I>first</I> is less than <I>last</I>. </DD>
+</DL>
+<P>
+Vector
+names must start with a letter and consist of letters, digits, or underscores.
+ <BR>
+<CODE># Error: must start with letter<BR>
+vector create 1abc<BR>
+</CODE>You can automatically generate vector names using the "#auto" vector
+name. The <B>create</B> operation will generate a unique vector name. <BR>
+<CODE>set vec [vector create #auto]<BR>
+puts "$vec has [$vec length] components"<BR>
+
+<H3><A NAME="sect6" HREF="#toc6"></CODE>Vector Indices</A></H3>
+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. <P>
+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 <B>offset</B> operation to change a vector's indices
+on-the-fly. <BR>
+<CODE>puts $vecName(0)<BR>
+vecName offset -5<BR>
+puts $vecName(-5)<BR>
+</CODE>When <I>matrix numcols</I> is > 1, 2D indexes are supported using ROW,COL form.
+<BR>
+<CODE>vecName matrix numcols 3<BR>
+puts vecName(0,2)<BR>
+</CODE>You can also use numeric expressions as indices. The result of the expression
+must be an integer value. <BR>
+<CODE>set n 21<BR>
+set vecName($n+3) 50.2<BR>
+</CODE>The following special non-numeric indices are available: min, max, end,
+and ++end. <BR>
+<CODE>puts "min = $vecName($min)"<BR>
+set vecName(end) -1.2<BR>
+</CODE>The indices min and max will return the minimum and maximum values
+of the vector. Also available are: prod, sum, and mean. The index
+end returns the value of the last component in the vector. he index end,0
+returns the value of the last row in column 0 of the vector. The index
+++end is used to append new value onto the vector. It automatically extends
+the vector by numcols and sets its value. <BR>
+<CODE># Append an new component to the end<BR>
+set vecName(++end) 3.2<BR>
+</CODE>A range of indices can be indicated by a colon (:). <BR>
+<CODE># Set the first six components to 1.0<BR>
+set vecName(0:5) 1.0<BR>
+</CODE>If no index is supplied the first or last component is assumed. <BR>
+<CODE># Print the values of all the components<BR>
+puts $vecName(:)<BR>
+
+<H2><A NAME="sect7" HREF="#toc7"></CODE>Vector Operations</A></H2>
+
+<DL>
+
+<DT><B>vector configure <I>? -flush bool -watchunset bool -oldcreate
+bool -maxsize int -novariable bool -nocommand bool?</I></B> </DT>
+<DD>The <B>configure</B> operation
+sets the default options used in creating vectors: these options are global
+to the interpreter. The <I>-maxsize</I> option, when non-zero, limits creation size.
+The <I>-oldcreate</I> enable the creation shortcut: <B>vector vec1 vec2 ...</B>. See the create
+command for details on the others. By default, these are all disabled or
+zero. </DD>
+</DL>
+</blockquote>
+
+<DL>
+
+<DT><B>vector create <I>vecName</I></B>?(<I>size</I>)?... ?<I>switches</I>? </DT>
+<DD>The <B>create</B> operation creates
+a new vector <I>vecName</I>. The <I>size</I> may be an integer, a START:END range or ROW,COL
+(see matrix). This creates both a Tcl command and array variable called
+<I>vecName</I>. The name <I>vecName</I> 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 <I>vecName</I> is unset, the vector and its Tcl
+command are also destroyed. <P>
+The vector has optional switches that affect
+how the vector is created. They are as follows: <blockquote></DD>
+
+<DT><B>-variable <I>varName</I></B> </DT>
+<DD>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 <I>varName</I> is the empty string,
+then no variable will be mapped. You can always map a variable back to the
+vector using the vector's <B>variable</B> operation. </DD>
+
+<DT><B>-command <I>cmdName</I></B> </DT>
+<DD>Maps a Tcl
+command to the vector. The vector can be accessed using <I>cmdName</I> and one
+of the vector instance operations. A Tcl command by that name cannot already
+exist. If <I>cmdName</I> is the empty string, no command mapping will be made. </DD>
+
+<DT><B>-watchunset
+<I>boolean</I></B> </DT>
+<DD>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 <I>boolean</I>
+to "true" to get the old behavior. </DD>
+
+<DT><B>-flush <I>boolean</I></B> </DT>
+<DD>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. </DD>
+</DL>
+</blockquote>
+
+<DL>
+
+<DT><B>vector destroy <I>vecName</I></B> ?<I>vecName...</I>? </DT>
+<DD>Destroy vectors. </DD>
+
+<DT><B>vector expr
+<I>expression</I></B> </DT>
+<DD><blockquote>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. <P>
+The valid operators are listed below,
+grouped in decreasing order of precedence: </DD>
+
+<DT><B>- !</B> </DT>
+<DD>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. </DD>
+
+<DT><B>^</B> </DT>
+<DD>Exponentiation. </DD>
+
+<DT><B>*
+ / %</B> </DT>
+<DD>Multiply, divide, remainder. </DD>
+
+<DT><B>+ -</B> </DT>
+<DD>Add and subtract. </DD>
+
+<DT><B><< >></B> </DT>
+<DD>Left and
+right shift. Circularly shifts the values of the vector </DD>
+
+<DT><B>< > <= >=</B> </DT>
+<DD>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. </DD>
+
+<DT><B>== !=</B> </DT>
+<DD>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. </DD>
+
+<DT><B>&&</B> </DT>
+<DD>Logical AND. Produces a 1 result if both
+operands are non-zero, 0 otherwise. </DD>
+
+<DT><B>||</B> </DT>
+<DD>Logical OR. Produces a 0 result if both
+operands are zero, 1 otherwise. </DD>
+
+<DT><I>x<B>?<I>y<B>:<I>z</I></B></I></B></I> </DT>
+<DD>If-then-else, as in C. </DD>
+</DL>
+<P>
+<P>
+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. <P>
+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. <BR>
+<CODE>vector create aVec<BR>
+aVec seq 0 100<BR>
+aVec expr {2*abs(aVec)-1}<BR>
+aVec length 100<BR>
+aVec expr {2*row()}<BR>
+vector expr {2*row()} ; # ERROR!<BR>
+<BR>
+</CODE><CODE><P>
+<B>acos</B><tt> </tt> <tt> </tt> <B>cos</B><tt> </tt> <tt> </tt> <B>hypot</B><tt> </tt> <tt> </tt> <B>sinh</B> <BR>
+<B>asin</B><tt> </tt> <tt> </tt> <B>cosh</B><tt> </tt> <tt> </tt> <B>log</B><tt> </tt> <tt> </tt> <B>sqrt</B> <BR>
+<B>atan</B><tt> </tt> <tt> </tt> <B>exp</B><tt> </tt> <tt> </tt> <B>log10</B><tt> </tt> <tt> </tt> <B>tan</B> <BR>
+<B>ceil</B><tt> </tt> <tt> </tt> <B>floor</B><tt> </tt> <tt> </tt> <B>sin</B><tt> </tt> <tt> </tt> <B>tanh</B> <BR>
+</CODE>Additional functions are:
+<DL>
+
+<DT><B>abs</B> </DT>
+<DD>Returns the absolute value of each component.
+</DD>
+
+<DT><B>random</B> </DT>
+<DD>Returns a vector of non-negative values uniformly distributed between
+[0.0, 1.0) using <I>drand48</I>. The seed comes from the internal clock of the machine
+or may be set manual with the srandom function. </DD>
+
+<DT><B>round</B> </DT>
+<DD>Rounds each component
+of the vector. </DD>
+
+<DT><B>srandom</B> </DT>
+<DD>Initializes the random number generator using <I>srand48</I>.
+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. </DD>
+</DL>
+<P>
+The following functions return a single
+value.
+<DL>
+
+<DT><B>adev</B> </DT>
+<DD>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). </DD>
+
+<DT><B>kurtosis</B> </DT>
+<DD>Returns the degree of peakedness (fourth
+moment) of the vector. </DD>
+
+<DT><B>length</B> </DT>
+<DD>Returns the number of components in the vector.
+</DD>
+
+<DT><B>max</B> </DT>
+<DD>Returns the vector's maximum value. </DD>
+
+<DT><B>mean</B> </DT>
+<DD>Returns the mean value of the
+vector. </DD>
+
+<DT><B>median</B> </DT>
+<DD>Returns the median of the vector. </DD>
+
+<DT><B>min</B> </DT>
+<DD>Returns the vector's
+minimum value. </DD>
+
+<DT><B>q1</B> </DT>
+<DD>Returns the first quartile of the vector. </DD>
+
+<DT><B>q3</B> </DT>
+<DD>Returns the
+third quartile of the vector. </DD>
+
+<DT><B>prod</B> </DT>
+<DD>Returns the product of the components.
+</DD>
+
+<DT><B>sdev</B> </DT>
+<DD>Returns the standard deviation (defined as the square root of the
+variance) of the vector. </DD>
+
+<DT><B>skew</B> </DT>
+<DD>Returns the skewness (or third moment) of
+the vector. This characterizes the degree of asymmetry of the vector about
+the mean. </DD>
+
+<DT><B>sum</B> </DT>
+<DD>Returns the sum of the components. </DD>
+
+<DT><B>var</B> </DT>
+<DD>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. </DD>
+</DL>
+<P>
+This last set of functions returns a vector of the
+same length as the argument.
+<DL>
+
+<DT><B>invert</B> </DT>
+<DD>Returns vector with elements in reversed
+order. </DD>
+
+<DT><B>norm</B> </DT>
+<DD>Scales the values of the vector to lie in the range [0.0..1.0].
+</DD>
+
+<DT><B>row</B> </DT>
+<DD>Psuedo function to get the current row. </DD>
+
+<DT><B>sort</B> </DT>
+<DD>Returns the vector components
+sorted in ascending order. </DD>
+
+<DT><B>shift(nVec,N)</B> </DT>
+<DD>This is the only function taking
+a second arg. It provides a version of <I>nvec</I> 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 <I>nVec</I> is used for the fill value. One use
+for this is providing running totals. </DD>
+</DL>
+</blockquote>
+
+<DL>
+
+<DT><B>vector names </B>?<I>pattern</I>? </DT>
+<DD>Return names
+of all defined vectors. </DD>
+</DL>
+</blockquote>
+
+<DL>
+
+<DT><B>vector op</B> <I>operation vecName</I> ?<I>arg</I>?... </DT>
+<DD>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. <BR>
+<P>
+<CODE>vector create v1<BR>
+v1 op append {1 2 3}<BR>
+v1 op modify 1 2.1<BR>
+<P>
+</DD>
+</DL>
+</blockquote>
+
+<H2><A NAME="sect8" HREF="#toc8"></CODE>Instance Operations</A></H2>
+You can also use the vector's Tcl command to query or
+modify it. The general form is <BR>
+<P>
+<CODE><I>vecName <I>operation</I></I> ?<I>arg</I>?...<BR>
+</CODE>Note this is equivalent to the form: <BR>
+<P>
+<CODE><B>vector op</B> <I>operation vecName</I> ?<I>arg</I>?...<BR>
+</CODE>Both <I>operation</I> and its arguments determine the exact behavior of the command.
+ The operations available for vectors are listed below.
+<DL>
+
+<DT><I>vecName <B>+</B></I> <I>item</I> </DT>
+<DD><I>vecName
+<B>-</B></I> <I>item</I> <I>vecName <B>*</B></I> <I>item</I> <I>vecName <B>/</B></I> <I>item</I> Perform binary op and return result
+as a list. </DD>
+
+<DT><I>vecName <B>append</B></I> <I>item</I> ?<I>item</I>?... </DT>
+<DD>Appends the component values from
+<I>item</I> to <I>vecName</I>. <I>Item</I> can be either the name of a vector or a list of numeric
+values. </DD>
+
+<DT><I>vecName <B>binread</B></I> <I>channel</I> ?<I>length</I>? ?<I>switches</I>? </DT>
+<DD>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 <B>-at</B> option), overwriting existing
+values. Data is read until EOF is found on the channel or a specified number
+of values <I>length</I> are read (note that this is not necessarily the same
+as the number of bytes). The following switches are supported: <blockquote></DD>
+
+<DT><B>-swap</B> </DT>
+<DD>Swap
+bytes and words. The default endian is the host machine. </DD>
+
+<DT><B>-at <I>index</I></B> </DT>
+<DD>New values
+will start at vector index <I>index</I>. This will overwrite any current values.
+</DD>
+
+<DT><B>-format</B> <I>format</I> </DT>
+<DD>Specifies the format of the data. <I>Format</I> 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". </DD>
+</DL>
+</blockquote>
+
+<DL>
+
+<DT><I>vecName <B>binwrite</B></I> <I>channel</I> ?<I>length</I>? ?<I>-at
+index</I>? </DT>
+<DD>Like <B>binread</B>, but writes data. </DD>
+
+<DT><I>vecName <B>clear</B></I> </DT>
+<DD>Clears the element
+indices from the array variable associated with <I>vecName</I>. 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. </DD>
+
+<DT><I>vecName <B>delete</B></I> <I>index</I> ?<I>index</I>?... </DT>
+<DD>Deletes the <I>index</I>th component from
+the vector <I>vecName</I>. <I>Index</I> is the index of the element to be deleted. This
+is the same as unsetting the array variable element <I>index</I>. The vector is
+compacted after all the indices have been deleted. </DD>
+
+<DT><I>vecName <B>dup</B></I> <I>destName</I>
+ </DT>
+<DD>Copies <I>vecName</I> to <I>destName</I>. <I>DestName</I> is the name of a destination vector.
+ If a vector <I>destName</I> already exists, it is overwritten with the components
+of <I>vecName</I>. Otherwise a new vector is created. </DD>
+
+<DT><I>vecName <B>expr</B></I> <I>expression</I>
+</DT>
+<DD>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. </DD>
+
+<DT><I>vecName <B>index</B></I> <I>index</I> ?<I>value</I>?... </DT>
+<DD>Get/set individual vector
+values. This provides element updating when <I>-variable</I> is set to empty. </DD>
+
+<DT><I>vecName
+<B>insert</B></I> <I>index</I> <I>item</I> ?<I>item</I>?... </DT>
+<DD>Inserts the component values from <I>item</I> to <I>vecName</I>
+at <I>index</I> <I>Item</I> can be either the name of a vector or a list of numeric values.
+</DD>
+
+<DT><I>vecName <B>length</B></I> ?<I>newSize</I>? </DT>
+<DD>Queries or resets the number of components in
+<I>vecName</I>. <I>NewSize</I> is a number specifying the new size of the vector. If <I>newSize</I>
+is smaller than the current size of <I>vecName</I>, <I>vecName</I> is truncated. If <I>newSize</I>
+is greater, the vector is extended and the new components are initialized
+to 0.0. If no <I>newSize</I> argument is present, the current length of the vector
+is returned. </DD>
+
+<DT><I>vecName <B>matrix <I> ...</I></B></I> </DT>
+<DD>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: <BR>
+<P>
+<CODE>vector create aVec(10,3)<BR>
+vector create bVec(30)<BR>
+bVec matrix numcols 3<BR>
+set aVec(0,0) 99<BR>
+set bVec(29,2) -99<BR>
+aVec append {5 6 7}; # aVec now has 11 rows.<BR>
+aVec append 1 2; # Now aVec has 13 rows!<BR>
+<P>
+</CODE>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. <blockquote></DD>
+
+<DT><I>vecName <B>matrix copy <I>dstcolumn</I></B></I> <I>srccolumn</I> <I>?srcVec?</I> </DT>
+<DD>Copy
+a column of element values to column <I>dstcolumn</I> from <I>srccolumn</I>. If vector
+<I>srcVec</I> is given, and not the same as <I>vecName</I>, the columns numbers must
+be different. If the <I>srcVec</I> column is longer, <I>vecName</I> will be extended. If
+shorter, remaining destination values are not overwritten. </DD>
+
+<DT><I>vecName <B>matrix
+delete <I>column</I></B></I>. </DT>
+<DD>Delete elements in a column. Note that <B>numcols</B>, which must
+be greater than 1, will be decremented. </DD>
+
+<DT><I>vecName <B>matrix get <I>column</I></B></I> </DT>
+<DD>Get the
+element in a column: this number must be less than <B>numcols</B>. Note that <B>numcols</B>
+must be non-zero. </DD>
+
+<DT><I>vecName <B>matrix insert <I>column</I></B></I> <I>?initvalue?</I> . </DT>
+<DD>Insert a new
+column of elements at column (default 0). The new column is initialized
+with <I>initvalue</I>, or <I>0.0</I> if not specified. Note that <B>numcols</B> will be incremented.
+</DD>
+
+<DT><I>vecName <B>matrix multiply <I>srcVec</I></B></I> ?<I>dstVec</I>? </DT>
+<DD>Perform matrix multiplication
+using <B>srcVec</B>, placing results either in <B>dstVec</B>, or returned as a list. The
+numrows of <I>srcVec</I> must equal numcols in <I>vecName</I>. One application for multiply
+is coordinate transformation. </DD>
+
+<DT><I>vecName <B>matrix numcols <I>?size?</I></B></I> </DT>
+<DD>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, <B>$vec1(1,2)</B> 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. </DD>
+
+<DT><I>vecName
+<B>matrix numrows <I>?size?</I></B></I> </DT>
+<DD>Get or set the length of rows in a columns for a
+vector. By default, this is just the <I>vector length/numcols</I>. Setting this
+value simply provides a convenient way to increase or decrease the vector
+size by multiples of <I>numcols</I>. </DD>
+
+<DT><I>vecName <B>matrix set <I>column</I></B></I> <I>?valuelist?</I> </DT>
+<DD>Set
+value elements in a column: this number must be less than <B>numcols</B>. The
+<I>valuelist</I> 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 <I>item</I>, or <I>0.0</I> by default. </DD>
+
+<DT><I>vecName <B>matrix shift <I>column</I></B></I> <I>amount</I> ?<I>startoffset</I>?
+</DT>
+<DD>Shifts the values of a column by integer in<I>amount</I>. A negative value shifts
+upward. The <I>startoffset</I> indicates where to start shifting from. </DD>
+
+<DT><I>vecName <B>matrix
+sort <I>column</I></B></I> <I>?-reverse?</I> </DT>
+<DD>Sort the vector by the given column. </DD>
+
+<DT><I>vecName <B>matrix
+transpose</B></I> </DT>
+<DD>Transpose all columns with rows in matrix. Note that this is a
+no-op if <B>numcols</B> is 1. Otherwise, numcols will change to <B>vectorLength/numcols</B>.
+</DD>
+</DL>
+</blockquote>
+
+<DL>
+
+<DT><I>vecName <B>merge</B></I> <I>srcName</I> ?<I>srcName</I>?... </DT>
+<DD>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. </DD>
+
+<DT><I>vecName <B>notify</B></I> ?<I>keyword</I>? ?<I>script</I>? </DT>
+<DD>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
+<I>keyword</I>. <blockquote></DD>
+
+<DT>always </DT>
+<DD>Indicates that clients are to be notified immediately
+whenever the vector is updated. </DD>
+
+<DT>never </DT>
+<DD>Indicates that no clients are to
+be notified. </DD>
+
+<DT>whenidle </DT>
+<DD>Indicates that clients are to be notified at the
+next idle point whenever the vector is updated. </DD>
+
+<DT>now </DT>
+<DD>If any client notifications
+is currently pending, they are notified immediately. </DD>
+
+<DT>cancel </DT>
+<DD>Cancels pending
+notifications of clients using the vector. </DD>
+
+<DT>pending </DT>
+<DD>Returns 1 if a client
+notification is pending, and 0 otherwise. </DD>
+
+<DT>callback ?<I>script</I>? </DT>
+<DD>Query or
+set a Tcl callback script that is evaluated when a vector is updated. </DD>
+</DL>
+</blockquote>
+
+<DL>
+
+<DT><I>vecName
+<B>populate</B></I> <I>destName</I> ?<I>density</I>? </DT>
+<DD>Creates a vector <I>destName</I> which is a superset
+of <I>vecName</I>. <I>DestName</I> will include all the components of <I>vecName</I>, in addition
+the interval between each of the original components will contain a <I>density</I>
+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. </DD>
+
+<DT><I>vecName <B>range</B></I> <I>firstIndex</I> ?<I>lastIndex</I>?... </DT>
+<DD>Returns
+a list of numeric values representing the vector components between two
+indices. Both <I>firstIndex</I> and <I>lastIndex</I> are indices representing the range
+of components to be returned. If <I>lastIndex</I> is less than <I>firstIndex</I>, the
+components are listed in reverse order. </DD>
+
+<DT><I>vecName <B>search</B></I> <I>value</I> ?<I>value</I>? </DT>
+<DD>Searches
+for a value or range of values among the components of <I>vecName</I>. If one
+<I>value</I> argument is given, a list of indices of the components which equal
+<I>value</I> is returned. If a second <I>value</I> 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 "" is returned. </DD>
+
+<DT><I>vecName <B>set</B></I> <I>item</I> </DT>
+<DD>Resets
+the components of the vector to <I>item</I>. <I>Item</I> can be either a list of numeric
+expressions or another vector. </DD>
+
+<DT><I>vecName <B>seq</B></I> <I>start</I> ?<I>finish</I>? ?<I>step</I>? </DT>
+<DD>Generates
+a sequence of values starting with the value <I>start</I>. <I>Finish</I> indicates the
+terminating value of the sequence. The vector is automatically resized
+to contain just the sequence. If three arguments are present, <I>step</I> designates
+the interval. <P>
+With only two arguments (no <I>finish</I> argument), the sequence
+will continue until the vector is filled. With one argument, the interval
+ defaults to 1.0. </DD>
+
+<DT><I>vecName <B>sort</B></I> ?<B>-reverse</B>? ?<I>argName</I>?... </DT>
+<DD>Sorts the vector <I>vecName</I>
+in increasing order. If the <B>-reverse</B> flag is present, the vector is sorted
+in decreasing order. If other arguments <I>argName</I> are present, they are the
+names of vectors which will be rearranged in the same manner as <I>vecName</I>.
+ Each vector must be the same length as <I>vecName</I>. 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. </DD>
+
+<DT><I>vecName <B>split</B></I> <I>dstName</I> ?<I>dstName</I>?... </DT>
+<DD>Split the vector into
+a multiple vectors. The resulting N vectors each contain the mod-Nth element
+from source. </DD>
+
+<DT><I>vecName <B>variable</B></I> <I>varName</I> </DT>
+<DD>Maps a Tcl variable to the vector,
+creating another means for accessing the vector. The variable <I>varName</I>
+can't already exist. This overrides any current variable mapping the vector
+may have. </DD>
+</DL>
+</blockquote>
+
+<H2><A NAME="sect9" HREF="#toc9">C Language API</A></H2>
+You can create, modify, and destroy vectors from
+C code, using library routines. You need to include the header file blt.h.
+It contains the definition of the structure <B>Blt_Vector</B>, which represents
+the vector. It appears below. <BR>
+<CODE>typedef struct {<BR>
+ double *<I>valueArr</I>; <BR>
+ int <I>numValues</I>; <BR>
+ int <I>arraySize</I>; <BR>
+ double <I>min</I>, <I>max</I>; <BR>
+} <B>Blt_Vector</B>;<BR>
+</CODE>The field <I>valueArr</I> points to memory holding the vector components. The
+components are stored in a double precision array, whose size size is represented
+by <I>arraySize</I>. <I>NumValues</I> is the length of vector. The size of the array
+is always equal to or larger than the length of the vector. <I>Min</I> and <I>max</I>
+are minimum and maximum component values.
+<H2><A NAME="sect10" HREF="#toc10">Library Routines</A></H2>
+The following
+routines are available from C to manage vectors. Vectors are identified
+by the vector name. <P>
+<B>Blt_CreateVector</B> <blockquote>
+<DL>
+
+<DT>Synopsis: </DT>
+<DD><BR>
+<CODE>int <B>Blt_CreateVector</B> (<I>interp</I>, <I>vecName</I>, <I>length</I>, <I>vecPtrPtr</I>)<BR>
+<blockquote>Tcl_Interp *<I>interp</I>;<BR>
+char *<I>vecName</I>;<BR>
+int <I>length</I>;<BR>
+Blt_Vector **<I>vecPtrPtr</I>;<BR>
+</DD>
+</DL>
+</blockquote>
+
+<DL>
+
+<DT></CODE>Description: </DT>
+<DD>Creates a new vector <I>vecName</I> with a length of <I>length</I>. <B>Blt_CreateVector</B>
+creates both a new Tcl command and array variable <I>vecName</I>. Neither a command
+nor variable named <I>vecName</I> can already exist. A pointer to the vector
+is placed into <I>vecPtrPtr</I>. </DD>
+
+<DT>Results: </DT>
+<DD>Returns TCL_OK if the vector is successfully
+created. If <I>length</I> is negative, a Tcl variable or command <I>vecName</I> already
+exists, or memory cannot be allocated for the vector, then TCL_ERROR
+is returned and <I>interp->result</I> will contain an error message. </DD>
+</DL>
+</blockquote>
+<P>
+<P>
+<B>Blt_DeleteVectorByName</B>
+ <blockquote>
+<DL>
+
+<DT>Synopsis: </DT>
+<DD><BR>
+<CODE>int <B>Blt_DeleteVectorByName</B> (<I>interp</I>, <I>vecName</I>)<BR>
+<blockquote>Tcl_Interp *<I>interp</I>;<BR>
+char *<I>vecName</I>;<BR>
+</DD>
+</DL>
+</blockquote>
+
+<DL>
+
+<DT></CODE>Description: </DT>
+<DD>Removes the vector <I>vecName</I>. <I>VecName</I> is the name of a vector
+which must already exist. Both the Tcl command and array variable <I>vecName</I>
+are destroyed. All clients of the vector will be notified immediately that
+the vector has been destroyed. </DD>
+
+<DT>Results: </DT>
+<DD>Returns TCL_OK if the vector is
+successfully deleted. If <I>vecName</I> is not the name a vector, then TCL_ERROR
+is returned and <I>interp->result</I> will contain an error message. </DD>
+</DL>
+</blockquote>
+<P>
+<P>
+<B>Blt_DeleteVector</B>
+ <blockquote>
+<DL>
+
+<DT>Synopsis: </DT>
+<DD><BR>
+<CODE>int <B>Blt_DeleteVector</B> (<I>vecPtr</I>)<BR>
+<blockquote>Blt_Vector *<I>vecPtr</I>;<BR>
+</DD>
+</DL>
+</blockquote>
+
+<DL>
+
+<DT></CODE>Description: </DT>
+<DD>Removes the vector pointed to by <I>vecPtr</I>. <I>VecPtr</I> is a pointer
+to a vector, typically set by <B>Blt_GetVector</B> or <B>Blt_CreateVector</B>. 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.
+</DD>
+
+<DT>Results: </DT>
+<DD>Returns TCL_OK if the vector is successfully deleted. If <I>vecName</I>
+is not the name a vector, then TCL_ERROR is returned and <I>interp->result</I>
+will contain an error message. </DD>
+</DL>
+</blockquote>
+<P>
+<P>
+<B>Blt_GetVector</B> <blockquote>
+<DL>
+
+<DT>Synopsis: </DT>
+<DD><BR>
+<CODE>int <B>Blt_GetVector</B> (<I>interp</I>, <I>vecName</I>, <I>vecPtrPtr</I>)<BR>
+<blockquote>Tcl_Interp *<I>interp</I>;<BR>
+char *<I>vecName</I>;<BR>
+Blt_Vector **<I>vecPtrPtr</I>;<BR>
+</DD>
+</DL>
+</blockquote>
+
+<DL>
+
+<DT></CODE>Description: </DT>
+<DD>Retrieves the vector <I>vecName</I>. <I>VecName</I> is the name of a vector
+which must already exist. <I>VecPtrPtr</I> will point be set to the address of
+the vector. </DD>
+
+<DT>Results: </DT>
+<DD>Returns TCL_OK if the vector is successfully retrieved.
+ If <I>vecName</I> is not the name of a vector, then TCL_ERROR is returned and
+<I>interp->result</I> will contain an error message. </DD>
+</DL>
+</blockquote>
+<P>
+<P>
+<B>Blt_ResetVector</B> <P>
+<blockquote>
+<DL>
+
+<DT>Synopsis: </DT>
+<DD><BR>
+<CODE>int <B>Blt_ResetVector</B> (<I>vecPtr</I>, <I>dataArr</I>, <BR>
+<tt> </tt> <tt> </tt> <I>numValues</I>, <I>arraySize</I>, <I>freeProc</I>)<BR>
+<blockquote>Blt_Vector *<I>vecPtr</I>;<BR>
+double *<I>dataArr</I>;<BR>
+int *<I>numValues</I>;<BR>
+int *<I>arraySize</I>;<BR>
+Tcl_FreeProc *<I>freeProc</I>;<BR>
+</DD>
+</DL>
+</blockquote>
+
+<DL>
+
+<DT></CODE>Description: </DT>
+<DD>Resets the components of the vector pointed to by <I>vecPtr</I>.
+Calling <B>Blt_ResetVector</B> will trigger the vector to dispatch notifications
+to its clients. <I>DataArr</I> is the array of doubles which represents the vector
+data. <I>NumValues</I> is the number of elements in the array. <I>ArraySize</I> is the
+actual size of the array (the array may be bigger than the number of values
+stored in it). <I>FreeProc</I> indicates how the storage for the vector component
+array (<I>dataArr</I>) was allocated. It is used to determine how to reallocate
+memory when the vector is resized or destroyed. It must be TCL_DYNAMIC,
+TCL_STATIC, TCL_VOLATILE, or a pointer to a function to free the memory
+allocated for the vector array. If <I>freeProc</I> is TCL_VOLATILE, it indicates
+that <I>dataArr</I> must be copied and saved. If <I>freeProc</I> is TCL_DYNAMIC, it
+indicates that <I>dataArr</I> was dynamically allocated and that Tcl should free
+<I>dataArr</I> if necessary. Static indicates that nothing should be done to
+release storage for <I>dataArr</I>. </DD>
+
+<DT>Results: </DT>
+<DD>Returns TCL_OK if the vector is
+successfully resized. If <I>newSize</I> is negative, a vector <I>vecName</I> does not
+exist, or memory cannot be allocated for the vector, then TCL_ERROR is
+returned and <I>interp->result</I> will contain an error message. </DD>
+</DL>
+</blockquote>
+<P>
+<P>
+<B>Blt_ResizeVector</B>
+ <blockquote>
+<DL>
+
+<DT>Synopsis: </DT>
+<DD><BR>
+<CODE>int <B>Blt_ResizeVector</B> (<I>vecPtr</I>, <I>newSize</I>)<BR>
+<blockquote>Blt_Vector *<I>vecPtr</I>;<BR>
+int <I>newSize</I>;<BR>
+</DD>
+</DL>
+</blockquote>
+
+<DL>
+
+<DT></CODE>Description: </DT>
+<DD>Resets the length of the vector pointed to by <I>vecPtr</I> to <I>newSize</I>.
+ If <I>newSize</I> is smaller than the current size of the vector, it is truncated.
+ If <I>newSize</I> is greater, the vector is extended and the new components are
+initialized to 0.0. Calling <B>Blt_ResetVector</B> will trigger the vector to
+dispatch notifications. </DD>
+
+<DT>Results: </DT>
+<DD>Returns TCL_OK if the vector is successfully
+resized. If <I>newSize</I> is negative or memory can not be allocated for the
+vector, then TCL_ERROR is returned and <I>interp->result</I> will contain an
+error message. <P>
+</DD>
+</DL>
+<P>
+<B>Blt_VectorExists</B> <blockquote>
+<DL>
+
+<DT>Synopsis: </DT>
+<DD><BR>
+<CODE>int <B>Blt_VectorExists</B> (<I>interp</I>, <I>vecName</I>)<BR>
+<blockquote>Tcl_Interp *<I>interp</I>;<BR>
+char *<I>vecName</I>;<BR>
+</DD>
+</DL>
+</blockquote>
+
+<DL>
+
+<DT></CODE>Description: </DT>
+<DD>Indicates if a vector named <I>vecName</I> exists in <I>interp</I>. </DD>
+
+<DT>Results:
+</DT>
+<DD>Returns 1 if a vector <I>vecName</I> exists and 0 otherwise. </DD>
+</DL>
+</blockquote>
+<P>
+<P>
+If your application
+needs to be notified when a vector changes, it can allocate a unique <I>client
+identifier</I> 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. <P>
+The call-back routine must of
+the following type. <BR>
+<blockquote><BR>
+<CODE>typedef void (<B>Blt_VectorChangedProc</B>) (Tcl_Interp *<I>interp</I>, <BR>
+<blockquote>ClientData <I>clientData</I>, Blt_VectorNotify <I>notify</I>);<BR>
+</blockquote>
+<BR>
+</blockquote>
+</PRE></CODE><I>ClientData</I> is passed to this routine whenever it is called. You can use
+this to pass information to the call-back. The <I>notify</I> argument indicates
+whether the vector has been updated of destroyed. It is an enumerated type.
+<BR>
+<blockquote><BR>
+<CODE>typedef enum {<BR>
+ BLT_VECTOR_NOTIFY_UPDATE=1,<BR>
+ BLT_VECTOR_NOTIFY_DESTROY=2<BR>
+} <B>Blt_VectorNotify</B>;<BR>
+<BR>
+</blockquote>
+<P>
+</CODE><B>Blt_AllocVectorId</B> <blockquote>
+<DL>
+
+<DT>Synopsis: </DT>
+<DD><BR>
+<CODE>Blt_VectorId <B>Blt_AllocVectorId</B> (<I>interp</I>, <I>vecName</I>)<BR>
+<blockquote>Tcl_Interp *<I>interp</I>;<BR>
+char *<I>vecName</I>;<BR>
+</DD>
+</DL>
+</blockquote>
+
+<DL>
+
+<DT></CODE>Description: </DT>
+<DD>Allocates an client identifier for with the vector <I>vecName</I>.
+This identifier can be used to specify a call-back which is triggered when
+the vector is updated or destroyed. </DD>
+
+<DT>Results: </DT>
+<DD>Returns a client identifier
+if successful. If <I>vecName</I> is not the name of a vector, then NULL is returned
+and <I>interp->result</I> will contain an error message. </DD>
+</DL>
+</blockquote>
+<P>
+<P>
+<B>Blt_GetVectorById</B> <blockquote>
+<DL>
+
+<DT>Synopsis:
+</DT>
+<DD><BR>
+<CODE>int <B>Blt_GetVector</B> (<I>interp</I>, <I>clientId</I>, <I>vecPtrPtr</I>)<BR>
+<blockquote>Tcl_Interp *<I>interp</I>;<BR>
+Blt_VectorId <I>clientId</I>;<BR>
+Blt_Vector **<I>vecPtrPtr</I>;<BR>
+</DD>
+</DL>
+</blockquote>
+
+<DL>
+
+<DT></CODE>Description: </DT>
+<DD>Retrieves the vector used by <I>clientId</I>. <I>ClientId</I> is a valid
+vector client identifier allocated by <B>Blt_AllocVectorId</B>. <I>VecPtrPtr</I> will
+point be set to the address of the vector. </DD>
+
+<DT>Results: </DT>
+<DD>Returns TCL_OK if
+the vector is successfully retrieved. </DD>
+</DL>
+</blockquote>
+<P>
+<P>
+<B>Blt_SetVectorChangedProc</B> <blockquote>
+<DL>
+
+<DT>Synopsis:
+</DT>
+<DD><BR>
+<CODE>void <B>Blt_SetVectorChangedProc</B> (<I>clientId</I>, <I>proc</I>, <I>clientData</I>);<BR>
+<blockquote>Blt_VectorId <I>clientId</I>;<BR>
+Blt_VectorChangedProc *<I>proc</I>;<BR>
+ClientData *<I>clientData</I>;<BR>
+</DD>
+</DL>
+</blockquote>
+
+<DL>
+
+<DT></CODE>Description: </DT>
+<DD>Specifies a call-back routine to be called whenever the vector
+associated with <I>clientId</I> is updated or deleted. <I>Proc</I> is a pointer to call-back
+routine and must be of the type <B>Blt_VectorChangedProc</B>. <I>ClientData</I> is a
+one-word value to be passed to the routine when it is invoked. If <I>proc</I> is
+NULL, then the client is not notified. </DD>
+
+<DT>Results: </DT>
+<DD>The designated call-back
+procedure will be invoked when the vector is updated or destroyed. </DD>
+</DL>
+</blockquote>
+<P>
+<P>
+<B>Blt_FreeVectorId</B>
+<blockquote>
+<DL>
+
+<DT>Synopsis: </DT>
+<DD><BR>
+<CODE>void <B>Blt_FreeVectorId</B> (<I>clientId</I>);<BR>
+<blockquote>Blt_VectorId <I>clientId</I>;<BR>
+</DD>
+</DL>
+</blockquote>
+
+<DL>
+
+<DT></CODE>Description: </DT>
+<DD>Frees the client identifier. Memory allocated for the identifier
+ is released. The client will no longer be notified when the vector is
+modified. </DD>
+
+<DT>Results: </DT>
+<DD>The designated call-back procedure will be no longer be
+invoked when the vector is updated or destroyed. </DD>
+</DL>
+</blockquote>
+<P>
+<P>
+<B>Blt_NameOfVectorId</B> <blockquote>
+<DL>
+
+<DT>Synopsis:
+</DT>
+<DD><BR>
+<CODE>char *<B>Blt_NameOfVectorId</B> (<I>clientId</I>);<BR>
+<blockquote>Blt_VectorId <I>clientId</I>;<BR>
+</DD>
+</DL>
+</blockquote>
+
+<DL>
+
+<DT></CODE>Description: </DT>
+<DD>Retrieves the name of the vector associated with the client
+identifier <I>clientId</I>. </DD>
+
+<DT>Results: </DT>
+<DD>Returns the name of the vector associated
+with <I>clientId</I>. If <I>clientId</I> is not an identifier or the vector has been
+destroyed, NULL is returned. </DD>
+</DL>
+</blockquote>
+<P>
+<P>
+<B>Blt_InstallIndexProc</B> <blockquote>
+<DL>
+
+<DT>Synopsis: </DT>
+<DD><BR>
+<CODE>void <B>Blt_InstallIndexProc</B> (<I>indexName</I>, <I>procPtr</I>)<BR>
+<blockquote>char *<I>indexName</I>;<BR>
+Blt_VectorIndexProc *<I>procPtr</I>;<BR>
+</DD>
+</DL>
+</blockquote>
+
+<DL>
+
+<DT></CODE>Description: </DT>
+<DD>Registers a function to be called to retrieved the index
+<I>indexName</I> from the vector's array variable. <P>
+typedef double Blt_VectorIndexProc(Vector
+*vecPtr); <P>
+The function will be passed a pointer to the vector. The function
+must return a double representing the value at the index. </DD>
+
+<DT>Results: </DT>
+<DD>The new
+index is installed into the vector. </DD>
+</DL>
+</blockquote>
+</blockquote>
+
+<H2><A NAME="sect11" HREF="#toc11">C API Example</A></H2>
+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
+<B>Blt_VectorExists</B>, <B>Blt_GetVector</B> is called to get the pointer to the vector.
+Otherwise the routine <B>Blt_CreateVector</B> 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 <B>lt_ResetVector</B> is called.
+ Blt_ResetVector makes the changes visible to the Tcl interface and other
+vector clients (such as a graph widget). <P>
+<BR>
+<CODE>#include <tcl.h><BR>
+#include <blt.h><tt> </tt> <tt> </tt> <tt> </tt> <tt> </tt> <tt> </tt> <tt> </tt> <tt> </tt> <tt> </tt> <BR>
+Blt_Vector *vecPtr;<BR>
+double *newArr;<BR>
+FILE *f;<BR>
+struct stat statBuf;<BR>
+int numBytes, numValues;<BR>
+<P>
+f = fopen("binary.dat", "r");<BR>
+fstat(fileno(f), &statBuf);<BR>
+numBytes = (int)statBuf.st_size;<BR>
+<P>
+/* Allocate an array big enough to hold all the data */<BR>
+newArr = (double *)m<A HREF="alloc.numBytes">alloc(numBytes)</A>
+;<BR>
+numValues = numBytes / sizeof(double);<BR>
+fread((void *)newArr, numValues, sizeof(double), f);<BR>
+fclose(f);<BR>
+<P>
+if (Blt_VectorExists(interp, "data")) {<BR>
+ if (Blt_GetVector(interp, "data", &vecPtr) != TCL_OK) {<BR>
+<tt> </tt> <tt> </tt> return TCL_ERROR;<BR>
+ }<BR>
+} else {<BR>
+ if (Blt_CreateVector(interp, "data", 0, &vecPtr) != TCL_OK) {<BR>
+<tt> </tt> <tt> </tt> return TCL_ERROR;<BR>
+ }<BR>
+}<BR>
+/* <BR>
+ * Reset the vector. Clients will be notified when Tk is idle. <BR>
+ * TCL_DYNAMIC tells the vector to free the memory allocated <BR>
+ * if it needs to reallocate or destroy the vector.<BR>
+ */<BR>
+if (Blt_ResetVector(vecPtr, newArr, numValues, numValues, <BR>
+<tt> </tt> <tt> </tt> TCL_DYNAMIC) != TCL_OK) {<BR>
+ return TCL_ERROR;<BR>
+}<BR>
+
+<H2><A NAME="sect12" HREF="#toc12"></CODE>Incompatibilities</A></H2>
+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. <BR>
+<CODE>proc doit {} {<BR>
+ # Temporary vector x<BR>
+ vector x(10)<BR>
+ set <A HREF="x.9">x(9)</A>
+ 2.0<BR>
+ ...<BR>
+}<BR>
+<P>
+</CODE>This has changed. Variables are not automatically destroyed when their
+variable is unset. You can restore the old behavior by setting the "-watchunset"
+switch.
+<H2><A NAME="sect13" HREF="#toc13"></CODE>Keywords</A></H2>
+vector, graph, widget <P>
+
+<HR><P>
+<A NAME="toc"><B>Table of Contents</B></A><P>
+<UL>
+<LI><A NAME="toc0" HREF="#sect0">Name</A></LI>
+<LI><A NAME="toc1" HREF="#sect1">Synopsis</A></LI>
+<LI><A NAME="toc2" HREF="#sect2">Description</A></LI>
+<LI><A NAME="toc3" HREF="#sect3">Introduction</A></LI>
+<LI><A NAME="toc4" HREF="#sect4">Example</A></LI>
+<LI><A NAME="toc5" HREF="#sect5">Syntax</A></LI>
+<UL>
+<LI><A NAME="toc6" HREF="#sect6">Vector Indices</A></LI>
+</UL>
+<LI><A NAME="toc7" HREF="#sect7">Vector Operations</A></LI>
+<LI><A NAME="toc8" HREF="#sect8">Instance Operations</A></LI>
+<LI><A NAME="toc9" HREF="#sect9">C Language API</A></LI>
+<LI><A NAME="toc10" HREF="#sect10">Library Routines</A></LI>
+<LI><A NAME="toc11" HREF="#sect11">C API Example</A></LI>
+<LI><A NAME="toc12" HREF="#sect12">Incompatibilities</A></LI>
+<LI><A NAME="toc13" HREF="#sect13">Keywords</A></LI>
+</UL>
+</BODY></HTML>
OSDN Git Service
