diff options
| author | William Joye <wjoye@cfa.harvard.edu> | 2017-01-04 19:54:17 (GMT) |
|---|---|---|
| committer | William Joye <wjoye@cfa.harvard.edu> | 2017-01-04 19:54:17 (GMT) |
| commit | f654b92094d21d5b3d197edc505799f1b9cd3c44 (patch) | |
| tree | 5a58d68e4e2e2b19d9ca7fa2be2ff634e57e3a8c /tkblt/doc/vector.html | |
| parent | dc750f3e329a241f24831da739509d90c996ec20 (diff) | |
| parent | ba1a25c6143d0f853d1d6225611d0c4222f9cfec (diff) | |
| download | blt-f654b92094d21d5b3d197edc505799f1b9cd3c44.zip blt-f654b92094d21d5b3d197edc505799f1b9cd3c44.tar.gz blt-f654b92094d21d5b3d197edc505799f1b9cd3c44.tar.bz2 | |
Merge commit 'ba1a25c6143d0f853d1d6225611d0c4222f9cfec' as 'tkblt'
Diffstat (limited to 'tkblt/doc/vector.html')
| -rw-r--r-- | tkblt/doc/vector.html | 704 |
1 files changed, 704 insertions, 0 deletions
diff --git a/tkblt/doc/vector.html b/tkblt/doc/vector.html new file mode 100644 index 0000000..ef097c6 --- /dev/null +++ b/tkblt/doc/vector.html @@ -0,0 +1,704 @@ +<HTML> +<BODY> +<PRE> +<!-- Manpage converted by man2html 3.0.1 --> + +</PRE> +<H2>SYNOPSIS</H2><PRE> + <B>blt::vector</B> <B>create</B> <I>vecName</I> ?<I>vecName</I>...? ?<I>switches</I>? + + <B>blt::vector</B> <B>destroy</B> <I>vecName</I> ?<I>vecName</I>...? + + <B>blt::vector</B> <B>expr</B> <I>expression</I> + + <B>blt::vector</B> <B>names</B> ?<I>pattern</I>...? + + +</PRE> +<H2>DESCRIPTION</H2><PRE> + The <B>vector</B> command creates an array of floating point values. The vec- + tor's components can be manipulated in three ways: through a Tcl array + variable, a Tcl command, or the C API. + + +</PRE> +<H2>INTRODUCTION</H2><PRE> + A vector is an ordered set of real numbers. The components of a vector + are indexed by integers. + + 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 analy- + sis 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. + + You could try to use Tcl's associative arrays as vectors. Tcl arrays + are easy to use. You can access individual elements randomly by speci- + fying the index, or the set the entire array by providing a list of + index and value pairs for each element. The disadvantages of associa- + tive arrays as vectors lie in the fact they are implemented as hash + tables. + + <B>o</B> 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 val- + ues between two indices. Nor can you sort an array. + + <B>o</B> 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. + + <B>o</B> 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 ele- + ment in the array. This makes it cumbersome to perform operations on + the array as a whole. + + The <B>vector</B> command tries to overcome these disadvantages while still + 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. # Set the first value. set <B>y(0)</B> 9.25 + puts "y has [y length] components" 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 ele- + ment of y. # This is an error. The vector only has 50 components. set + <B>y(50)</B> 0.02 You can also specify a range of indices using a colon (:) to + separate the first and last indices of the range. # Set the first six + components of y set y(0:5) 25.2 If you don't include an index, then it + will default to the first and/or last component of the vector. # Print + out all the components of y puts "y = $y(:)" 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 com- + ponent and initialize it to a specific value. You can't read from the + array using this index, though. # Extend the vector by one component. + set y(++end) 0.02 The other special indices are min and max. They + return the current smallest and largest components of the vector. # + Print the bounds of the vector puts "min=$y(min) max=$y(max)" 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. # Delete the first component unset + <B>y(0)</B> puts "new first element is $<B>y(0)</B>" The vector's Tcl command can + also be used to query or set the vector. # Create and set the compo- + nents of a new vector blt::vector create x x set { 0.02 0.04 0.06 0.08 + 0.10 0.12 0.14 0.16 0.18 0.20 } 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. + + There are several operations for vectors. The <B>range</B> operation lists + the components of a vector between two indices. # List the components + puts "x = [x range 0 end]" 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 + "". # Find the index of the biggest component set indices [x search + $x(max)] Other operations copy, append, or sort vectors. You can + append vectors or new values onto an existing vector with the <B>append</B> + operation. # Append assorted vectors and values to x x append x2 x3 { + 2.3 4.5 } x4 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. # Sort the data points x sort y The vector x is + sorted while the components of y are rearranged so that the original + x,y coordinate pairs are retained. + + The <B>expr</B> operation lets you perform arithmetic on vectors. The result + is stored in the vector. # Add the two vectors and a scalar x expr { x + + y } x expr { x * 2 } When a vector is modified, resized, or deleted, + Vectors are created using the <B>vector</B> <B>create</B> operation. Th <B>create</B> oper- + ation can be invoked in one of three forms: + + <B>blt::vector</B> <B>create</B> <I>vecName</I> + This creates a new vector <I>vecName</I> which initially has no compo- + nents. + + <B>blt::vector</B> <B>create</B> <I>vecName</I>(<I>size</I>) + 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. + + <B>blt::vector</B> <B>create</B> <I>vecName</I>(<I>first</I>:<I>last</I>) + 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>. + + Vector names must start with a letter and consist of letters, digits, + or underscores. # Error: must start with letter blt::vector create + 1abc You can automatically generate vector names using the "#auto" vec- + tor name. The <B>create</B> operation will generate a unique vector name. + set vec [blt::vector create #auto] puts "$vec has [$vec length] compo- + nents" + + <B>VECTOR</B> <B>INDICES</B> + Vectors are indexed by integers. You can access the individual vector + components via its array variable or Tcl command. The string repre- + senting the index can be an integer, a numeric expression, a range, or + a special keyword. + + 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 vec- + tor's indices on-the-fly. puts $<B>vecName(0)</B> vecName offset -5 puts + $vecName(-5) You can also use numeric expressions as indices. The + result of the expression must be an integer value. set n 21 set vec- + Name($n+3) 50.2 The following special non-numeric indices are avail- + able: min, max, end, and ++end. puts "min = $vecName($min)" set vec- + Name(end) -1.2 The indices min and max will return the minimum and max- + imum values of the vector. The index end returns the value of the last + component in the vector. The index ++end is used to append new value + onto the vector. It automatically extends the vector by one component + and sets its value. # Append an new component to the end set vec- + Name(++end) 3.2 A range of indices can be indicated by a colon (:). # + Set the first six components to 1.0 set vecName(0:5) 1.0 If no index is + supplied the first or last component is assumed. # Print the values of + all the components puts $vecName(:) + + +</PRE> +<H2>VECTOR OPERATIONS</H2><PRE> + <B>blt::vector</B> <B>create</B> <I>vecName</I>?(<I>size</I>)?... ?<I>switches</I>? + 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 + then no variable will be mapped. You can always map a + variable back to the vector using the vector's <B>variable</B> + operation. + + <B>-command</B> <I>cmdName</I> + 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 map- + ping will be made. + + <B>-watchunset</B> <I>boolean</I> + 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. + + <B>blt::vector</B> <B>destroy</B> <I>vecName</I> ?<I>vecName...</I>? + Deletes one or more vectors. Both the Tcl command and array + variable are removed also. + + <B>blt::vector</B> <B>expr</B> <I>expression</I> + 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 oper- + and. 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 com- + ponent, 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. + + The valid operators are listed below, grouped in decreasing + order of precedence: + + <B>-</B> <B>!</B> 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. + + <B>^</B> Exponentiation. + + <B>*</B> <B>/</B> <B>%</B> Multiply, divide, remainder. + + <B>+</B> <B>-</B> Add and subtract. + + <B><<</B> <B>>></B> Left and right shift. Circularly shifts the + values of the vector (not implemented yet). + + <B>&&</B> Logical AND. Produces a 1 result if both + operands are non-zero, 0 otherwise. + + <B>||</B> Logical OR. Produces a 0 result if both op- + erands are zero, 1 otherwise. + + <I>x</I><B>?</B><I>y</I><B>:</B><I>z</I> If-then-else, as in C. (Not implemented + yet). + + 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. + + 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. + <B>acos</B> <B>cos</B> <B>hypot</B> <B>sinh</B> <B>asin</B> <B>cosh</B> <B>log</B> <B>sqrt</B> + <B>atan</B> <B>exp</B> <B>log10</B> <B>tan</B> <B>ceil</B> <B>floor</B> <B>sin</B> <B>tanh</B> + + Additional functions are: + + <B>abs</B> Returns the absolute value of each component. + + <B>random</B> Returns a vector of non-negative values uniformly dis- + tributed 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. + + <B>round</B> Rounds each component of the vector. + + <B>srandom</B> Initializes the random number generator using <I>srand48</I>. + The high order 32-bits are set using the integral por- + tion of the first vector component. All other compo- + nents are ignored. The low order 16-bits are set to + an arbitrary value. + + The following functions return a single value. + + <B>adev</B> Returns the average deviation (defined as the sum of + the absolute values of the differences between compo- + nent and the mean, divided by the length of the vec- + tor). + + <B>kurtosis</B> Returns the degree of peakedness (fourth moment) of + the vector. + + <B>length</B> Returns the number of components in the vector. + + <B>max</B> Returns the vector's maximum value. + + + <B>skew</B> Returns the skewness (or third moment) of the vector. + This characterizes the degree of asymmetry of the vec- + tor about the mean. + + <B>sum</B> Returns the sum of the components. + + <B>var</B> 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. + + The last set returns a vector of the same length as the argu- + ment. + + <B>norm</B> Scales the values of the vector to lie in the range + [0.0..1.0]. + + <B>sort</B> Returns the vector components sorted in ascending + order. + + <B>vector</B> <B>names</B> ?<I>pattern</I>? + + +</PRE> +<H2>INSTANCE OPERATIONS</H2><PRE> + You can also use the vector's Tcl command to query or modify it. The + general form is <I>vecName</I> <I>operation</I> ?<I>arg</I>?... Both <I>operation</I> and its + arguments determine the exact behavior of the command. The operations + available for vectors are listed below. + + <I>vecName</I> <B>append</B> <I>item</I> ?<I>item</I>?... + 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. + + <I>vecName</I> <B>binread</B> <I>channel</I> ?<I>length</I>? ?<I>switches</I>? + 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 sup- + ported: + + <B>-swap</B> Swap bytes and words. The default endian is the host + machine. + + <B>-at</B> <I>index</I> + New values will start at vector index <I>index</I>. This will + overwrite any current values. + + <B>-format</B> <I>format</I> + Specifies the format of the data. <I>Format</I> can be one of + the following: "i1", "i2", "i4", "i8", "u1, "u2", "u4", + + This is useful when the vector is large. + + <I>vecName</I> <B>delete</B> <I>index</I> ?<I>index</I>?... + 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 com- + pacted after all the indices have been deleted. + + <I>vecName</I> <B>dup</B> <I>destName</I> + Copies <I>vecName</I> to <I>destName</I>. <I>DestName</I> is the name of a destina- + tion vector. If a vector <I>destName</I> already exists, it is over- + written with the components of <I>vecName</I>. Otherwise a new vector + is created. + + <I>vecName</I> <B>expr</B> <I>expression</I> + 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 vec- + tors. + + <I>vecName</I> <B>length</B> ?<I>newSize</I>? + 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 trun- + cated. 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. + + <I>vecName</I> <B>merge</B> <I>srcName</I> ?<I>srcName</I>?... + 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. + + <I>vecName</I> <B>notify</B> <I>keyword</I> + Controls how vector clients are notified of changes to the vec- + tor. The exact behavior is determined by <I>keyword</I>. + + always Indicates that clients are to be notified immediately + whenever the vector is updated. + + never Indicates that no clients are to be notified. + + whenidle + Indicates that clients are to be notified at the next + idle point whenever the vector is updated. + + now If any client notifications is currently pending, they + are notified immediately. + + cancel Cancels pending notifications of clients using the vec- + tor. + + <I>density</I> number of new components, whose values are evenly dis- + tributed between the original components values. This is useful + for generating abscissas to be interpolated along a spline. + + <I>vecName</I> <B>range</B> <I>firstIndex</I> ?<I>lastIndex</I>?... + Returns a list of numeric values representing the vector compo- + nents 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. + + <I>vecName</I> <B>search</B> <I>value</I> ?<I>value</I>? + 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 compo- + nents are found, then "" is returned. + + <I>vecName</I> <B>set</B> <I>item</I> + Resets the components of the vector to <I>item</I>. <I>Item</I> can be either + a list of numeric expressions or another vector. + + <I>vecName</I> <B>seq</B> <I>start</I> ?<I>finish</I>? ?<I>step</I>? + 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. + + 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. + + <I>vecName</I> <B>sort</B> ?<B>-reverse</B>? ?<I>argName</I>?... + 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 vec- + tors 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. + + <I>vecName</I> <B>variable</B> <I>varName</I> + 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. + + +</PRE> +<H2>C LANGUAGE API</H2><PRE> + 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. typedef struct { + <B>Blt_CreateVector</B> + + Synopsis: int <B>Blt_CreateVector</B> (<I>interp</I>, <I>vecName</I>, <I>length</I>, <I>vecPtrPtr</I>) + Tcl_Interp *<I>interp</I>; char *<I>vecName</I>; int <I>length</I>; Blt_Vec- + tor **<I>vecPtrPtr</I>; + + Description: + 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>. + + Results: 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 vec- + tor, then TCL_ERROR is returned and <I>interp->result</I> will + contain an error message. + + + <B>Blt_DeleteVectorByName</B> + + Synopsis: int <B>Blt_DeleteVectorByName</B> (<I>interp</I>, <I>vecName</I>) + Tcl_Interp *<I>interp</I>; char *<I>vecName</I>; + + Description: + Removes the vector <I>vecName</I>. <I>VecName</I> is the name of a vec- + tor 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. + + Results: 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. + + + <B>Blt_DeleteVector</B> + + Synopsis: int <B>Blt_DeleteVector</B> (<I>vecPtr</I>) + Blt_Vector *<I>vecPtr</I>; + + Description: + 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. + + Results: Returns TCL_OK if the vector is successfully deleted. If + <I>vecName</I> is not the name a vector, then TCL_ERROR is + + Results: 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. + + + <B>Blt_ResetVector</B> + + + Synopsis: int <B>Blt_ResetVector</B> (<I>vecPtr</I>, <I>dataArr</I>, <I>numValues</I>, + <I>arraySize</I>, <I>freeProc</I>) + Blt_Vector *<I>vecPtr</I>; double *<I>dataArr</I>; int *<I>numValues</I>; int + *<I>arraySize</I>; Tcl_FreeProc *<I>freeProc</I>; + + Description: + 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 dou- + bles 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 vec- + tor 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>. + + Results: 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 mes- + sage. + + + <B>Blt_ResizeVector</B> + + Synopsis: int <B>Blt_ResizeVector</B> (<I>vecPtr</I>, <I>newSize</I>) + Blt_Vector *<I>vecPtr</I>; int <I>newSize</I>; + + Description: + 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. + + Results: Returns 1 if a vector <I>vecName</I> exists and 0 otherwise. + + + If your application needs to be notified when a vector changes, it + can allocate a unique <I>client</I> <I>identifier</I> for itself. Using this iden- + tifier, 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 iden- + tifier for any vector. When the client application is done with the + vector, it should free the identifier. + + The call-back routine must of the following type. + + typedef void (<B>Blt_VectorChangedProc</B>) (Tcl_Interp *<I>interp</I>, + ClientData <I>clientData</I>, Blt_VectorNotify <I>notify</I>); + + <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. + + typedef enum { + BLT_VECTOR_NOTIFY_UPDATE=1, + BLT_VECTOR_NOTIFY_DESTROY=2 } <B>Blt_VectorNotify</B>; + + + <B>Blt_AllocVectorId</B> + + Synopsis: Blt_VectorId <B>Blt_AllocVectorId</B> (<I>interp</I>, <I>vecName</I>) + Tcl_Interp *<I>interp</I>; char *<I>vecName</I>; + + Description: + Allocates an client identifier for with the vector <I>vec-</I> + <I>Name</I>. This identifier can be used to specify a call- + back which is triggered when the vector is updated or + destroyed. + + Results: 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. + + + <B>Blt_GetVectorById</B> + + Synopsis: int <B>Blt_GetVector</B> (<I>interp</I>, <I>clientId</I>, <I>vecPtrPtr</I>) + Tcl_Interp *<I>interp</I>; Blt_VectorId <I>clientId</I>; Blt_Vector + **<I>vecPtrPtr</I>; + + Description: + Retrieves the vector used by <I>clientId</I>. <I>ClientId</I> is a + valid vector client identifier allocated by + 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 noti- + fied. + + Results: The designated call-back procedure will be invoked when + the vector is updated or destroyed. + + + <B>Blt_FreeVectorId</B> + + Synopsis: void <B>Blt_FreeVectorId</B> (<I>clientId</I>); + Blt_VectorId <I>clientId</I>; + + Description: + Frees the client identifier. Memory allocated for the + identifier is released. The client will no longer be + notified when the vector is modified. + + Results: The designated call-back procedure will be no longer be + invoked when the vector is updated or destroyed. + + + <B>Blt_NameOfVectorId</B> + + Synopsis: char *<B>Blt_NameOfVectorId</B> (<I>clientId</I>); + Blt_VectorId <I>clientId</I>; + + Description: + Retrieves the name of the vector associated with the + client identifier <I>clientId</I>. + + Results: 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. + + + <B>Blt_InstallIndexProc</B> + + Synopsis: void <B>Blt_InstallIndexProc</B> (<I>indexName</I>, <I>procPtr</I>) + char *<I>indexName</I>; Blt_VectorIndexProc *<I>procPtr</I>; + + Description: + Registers a function to be called to retrieved the index + <I>indexName</I> from the vector's array variable. + + typedef double Blt_VectorIndexProc(Vector *vecPtr); + + The function will be passed a pointer to the vector. + + 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). + + #include <tcl.h> #include <blt.h> Blt_Vector *vecPtr; double + *newArr; FILE *f; struct stat statBuf; int numBytes, numValues; + + f = fopen("binary.dat", "r"); fstat(fileno(f), &statBuf); numBytes = + (int)statBuf.st_size; + + /* Allocate an array big enough to hold all the data */ newArr = (dou- + ble *)malloc(numBytes); numValues = numBytes / sizeof(double); + fread((void *)newArr, numValues, sizeof(double), f); fclose(f); + + if (Blt_VectorExists(interp, "data")) { + if (Blt_GetVector(interp, "data", &vecPtr) != TCL_OK) { + return TCL_ERROR; + } } else { + if (Blt_CreateVector(interp, "data", 0, &vecPtr) != TCL_OK) { + return TCL_ERROR; + } } /* + * Reset the vector. Clients will be notified when Tk is idle. + * TCL_DYNAMIC tells the vector to free the memory allocated + * if it needs to reallocate or destroy the vector. + */ if (Blt_ResetVector(vecPtr, newArr, numValues, numValues, + TCL_DYNAMIC) != TCL_OK) { + return TCL_ERROR; } + + +</PRE> +<H2>INCOMPATIBILITIES</H2><PRE> + In previous versions, if the array variable isn't global (i.e. local to + a Tcl procedure), the vector is automatically destroyed when the proce- + dure returns. proc doit {} { + # Temporary vector x + vector <B>x(10)</B> + set <B>x(9)</B> 2.0 + ... } + + This has changed. Variables are not automatically destroyed when their + variable is unset. You can restore the old behavior by setting the + "-watchunset" switch. + + +</PRE> +<H2>KEYWORDS</H2><PRE> + vector, graph, widget + + + +BLT BLT_VERSION blt::vector(n) +</PRE> +<HR> +<ADDRESS> +Man(1) output converted with +<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a> +</ADDRESS> +</BODY> +</HTML> |