diff options
Diffstat (limited to 'blt/html/vector.html')
-rw-r--r-- | blt/html/vector.html | 1124 |
1 files changed, 1124 insertions, 0 deletions
diff --git a/blt/html/vector.html b/blt/html/vector.html new file mode 100644 index 00000000000..c89a044c645 --- /dev/null +++ b/blt/html/vector.html @@ -0,0 +1,1124 @@ + <!-- manual page source format generated by PolyglotMan v3.0.8+XFree86, --> +<!-- available via anonymous ftp from ftp.cs.berkeley.edu:/ucb/people/phelps/tcltk/rman.tar.Z --> + +<HTML> +<HEAD> +<TITLE>vector(n) manual page</TITLE> +</HEAD> +<BODY BGCOLOR="#efefef" TEXT="black" LINK="blue" VLINK="#551A8B" ALINK="red"> +<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 +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>...? +<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 have +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><P>This creates a new vector named <I>y</I>. It has fifty components, by default, +initialized to <I>0.0</I>. In addition, both a Tcl command and array variable, +both named <I>y</I>, 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><P>The array <I>y</I> 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 <I>y</I>. <BR> +<CODE># This is an error. The vector only has 50 components.<BR> +set y(50) 0.02<BR> +</CODE><P>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><P>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><P>There are special non-numeric indices. The index <I>end</I>, 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 <I>++end</I> 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><P>The other special indices are <I>min</I> and <I>max</I>. 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><P>To delete components from a vector, simply unset the corresponding array +element. In the following example, the first component of <I>y</I> is deleted. +All the remaining components of <I>y</I> 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><P>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><P>Here we've created a vector <I>x</I> 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><P>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 <I>""</I>. <BR> +<CODE># Find the index of the biggest component<BR> +set indices [x search $x(max)]<BR> +</CODE><P>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><P>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><P>The vector <I>x</I> is sorted while the components of <I>y</I> 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><P>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> +</CODE><P>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> + +<H2><A NAME="sect5" HREF="#toc5"></CODE><P>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 <I>0.0</I>. </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><P>You can automatically generate vector names using the "<I>#auto</I>" 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><P>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><P>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><P>The following special non-numeric indices are available: <I>min</I>, <I>max</I>, <I>end</I>, +and <I>++end</I>. <BR> +<CODE>puts "min = $vecName($min)"<BR> +set vecName(end) -1.2<BR> +</CODE><P>The indices <I>min</I> and <I>max</I> will return the minimum and maximum values of the +vector. The index <I>end</I> returns the value of the last component in the vector. + The index <I>++end</I> is used to append new value onto the vector. It automatically +extends the vector by one component and sets its value. <BR> +<CODE># Append an new component to the end<BR> +set vecName(++end) 3.2<BR> +</CODE><P>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><P>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><P>Vector Operations</A></H2> + +<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>. Both a Tcl command and array variable <I>vecName</I> +are also created. The name <I>vecName</I> must be unique, so another Tcl command +or array variable can not already exist in that scope. You can access the +components of the vector using its variable. If you change a value in the +array, or unset an array element, the vector is updated to reflect the +changes. When the variable <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> +</DL> +</blockquote> + +<DL> + +<DT><B>vector destroy <I>vecName</I></B> ?<I>vecName...</I>? </DT> +<DD></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 (not implemented +yet). </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>Bit-wise OR. + (Not implemented). </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. (Not implemented yet). +</DD> +</DL> +<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. <BR> +<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><P>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> +The last set returns a vector of the same length +as the argument. +<DL> + +<DT><B>norm</B> </DT> +<DD>Scales the values of the vector to lie in the range +[0.0..1.0]. </DD> + +<DT><B>sort</B> </DT> +<DD>Returns the vector components sorted in ascending order. </DD> +</DL> +</blockquote> + +<DL> + +<DT><B>vector +names </B>?<I>pattern</I>? </DT> +<DD></DD> +</DL> + +<H2><A NAME="sect8" HREF="#toc8">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><P>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>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>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>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 <I>0.0</I>. If no <I>newSize</I> argument is present, the +current length of the vector is returned. </DD> + +<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> </DT> +<DD>Controls how vector clients are notified of +changes to the vector. The exact behavior is determined by <I>keyword</I>. <blockquote></DD> + +<DT><I>always</I> + </DT> +<DD>Indicates that clients are to be notified immediately whenever the vector +is updated. </DD> + +<DT><I>never</I> </DT> +<DD>Indicates that no clients are to be notified. </DD> + +<DT><I>whenidle</I> +</DT> +<DD>Indicates that clients are to be notified at the next idle point whenever +the vector is updated. </DD> + +<DT><I>now</I> </DT> +<DD>If any client notifications is currently pending, +they are notified immediately. </DD> + +<DT><I>cancel</I> </DT> +<DD>Cancels pending notifications of clients +using the vector. </DD> + +<DT><I>pending</I> </DT> +<DD>Returns <I>1</I> if a client notification is pending, +and <I>0</I> otherwise. </DD> +</DL> +</blockquote> + +<DL> + +<DT><I>vecName <B>offset</B></I> ?<I>value</I>? </DT> +<DD>Shifts the indices of the vector +by the amount specified by <I>value</I>. <I>Value</I> is an integer number. If no <I>value</I> +argument is given, the current offset is returned. </DD> + +<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 <I>""</I> 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>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 <I>blt.h</I>. 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><P>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><P>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 <I>TCL_OK</I> 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 <I>TCL_ERROR</I> 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><P>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 <I>TCL_OK</I> if the vector is +successfully deleted. If <I>vecName</I> is not the name a vector, then <I>TCL_ERROR</I> +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><P>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 <I>TCL_OK</I> if the vector is successfully deleted. If <I>vecName</I> +is not the name a vector, then <I>TCL_ERROR</I> 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><P>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 <I>TCL_OK</I> if the vector is successfully retrieved. + If <I>vecName</I> is not the name of a vector, then <I>TCL_ERROR</I> 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><P>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 <I>TCL_DYNAMIC</I>, +<I>TCL_STATIC</I>, <I>TCL_VOLATILE</I>, or a pointer to a function to free the memory +allocated for the vector array. If <I>freeProc</I> is <I>TCL_VOLATILE</I>, it indicates +that <I>dataArr</I> must be copied and saved. If <I>freeProc</I> is <I>TCL_DYNAMIC</I>, it indicates +that <I>dataArr</I> was dynamically allocated and that Tcl should free <I>dataArr</I> +if necessary. <I>Static</I> indicates that nothing should be done to release storage +for <I>dataArr</I>. </DD> + +<DT>Results: </DT> +<DD>Returns <I>TCL_OK</I> 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 <I>TCL_ERROR</I> 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><P>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 <I>0.0</I>. Calling <B>Blt_ResetVector</B> will trigger the vector to dispatch +notifications. </DD> + +<DT>Results: </DT> +<DD>Returns <I>TCL_OK</I> if the vector is successfully resized. + If <I>newSize</I> is negative or memory can not be allocated for the vector, + then <I>TCL_ERROR</I> 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><P>Description: </DT> +<DD>Indicates if a vector named <I>vecName</I> exists in <I>interp</I>. </DD> + +<DT>Results: +</DT> +<DD>Returns <I>1</I> if a vector <I>vecName</I> exists and <I>0</I> 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><P><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> + <I>BLT_VECTOR_NOTIFY_UPDATE</I>=1,<BR> + <I>BLT_VECTOR_NOTIFY_DESTROY</I>=2<BR> +} <B>Blt_VectorNotify</B>;<BR> +<BR> +</blockquote> +<P> +</CODE><P><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><P>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 <I>NULL</I> 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><P>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 <I>TCL_OK</I> 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><P>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 +<I>NULL</I>, 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><P>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><P>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, <I>NULL</I> 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><P>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.n.html">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><P>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.html">x(9)</A> + 2.0<BR> + ...<BR> +}<BR> +<P> +</CODE><P>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><P>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> |