diff options
| author | William Joye <wjoye@cfa.harvard.edu> | 2019-01-02 21:50:36 (GMT) |
|---|---|---|
| committer | William Joye <wjoye@cfa.harvard.edu> | 2019-01-02 21:50:36 (GMT) |
| commit | 4b458dac3f0ea680db57779eb3684e2136680306 (patch) | |
| tree | 2b61d5f91c71b718dbee8631eccbbf3d47528432 /tkblt/doc/vector.html | |
| parent | d2825c8167bd0d1f1daa937aa3b6ab21f7522527 (diff) | |
| download | blt-4b458dac3f0ea680db57779eb3684e2136680306.zip blt-4b458dac3f0ea680db57779eb3684e2136680306.tar.gz blt-4b458dac3f0ea680db57779eb3684e2136680306.tar.bz2 | |
update TEA 3.13
Diffstat (limited to 'tkblt/doc/vector.html')
| -rw-r--r-- | tkblt/doc/vector.html | 704 |
1 files changed, 0 insertions, 704 deletions
diff --git a/tkblt/doc/vector.html b/tkblt/doc/vector.html deleted file mode 100644 index ef097c6..0000000 --- a/tkblt/doc/vector.html +++ /dev/null @@ -1,704 +0,0 @@ -<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> |