summaryrefslogtreecommitdiffstats
path: root/tkblt/doc/vector.html
diff options
context:
space:
mode:
authorWilliam Joye <wjoye@cfa.harvard.edu>2019-01-02 21:50:36 (GMT)
committerWilliam Joye <wjoye@cfa.harvard.edu>2019-01-02 21:50:36 (GMT)
commit4b458dac3f0ea680db57779eb3684e2136680306 (patch)
tree2b61d5f91c71b718dbee8631eccbbf3d47528432 /tkblt/doc/vector.html
parentd2825c8167bd0d1f1daa937aa3b6ab21f7522527 (diff)
downloadblt-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.html704
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>&lt;&lt;</B> <B>&gt;&gt;</B> Left and right shift. Circularly shifts the
- values of the vector (not implemented yet).
-
- <B>&amp;&amp;</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-&gt;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-&gt;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-&gt;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-&gt;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-&gt;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 &lt;tcl.h&gt; #include &lt;blt.h&gt; Blt_Vector *vecPtr; double
- *newArr; FILE *f; struct stat statBuf; int numBytes, numValues;
-
- f = fopen("binary.dat", "r"); fstat(fileno(f), &amp;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", &amp;vecPtr) != TCL_OK) {
- return TCL_ERROR;
- } } else {
- if (Blt_CreateVector(interp, "data", 0, &amp;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>