2 '\" Copyright 1991-1997 by Lucent Technologies, Inc.
4 '\" Permission to use, copy, modify, and distribute this software and its
5 '\" documentation for any purpose and without fee is hereby granted, provided
6 '\" that the above copyright notice appear in all copies and that both that the
7 '\" copyright notice and warranty disclaimer appear in supporting documentation,
8 '\" and that the names of Lucent Technologies any of their entities not be used
9 '\" in advertising or publicity pertaining to distribution of the software
10 '\" without specific, written prior permission.
12 '\" Lucent Technologies disclaims all warranties with regard to this software,
13 '\" including all implied warranties of merchantability and fitness. In no event
14 '\" shall Lucent Technologies be liable for any special, indirect or
15 '\" consequential damages or any damages whatsoever resulting from loss of use,
16 '\" data or profits, whether in an action of contract, negligence or other
17 '\" tortuous action, arising out of or in connection with the use or performance
20 '\" Vector command created by George Howlett.
22 '\" The definitions below are for supplemental macros used in Tcl/Tk
25 '\" .AP type name in/out ?indent?
26 '\" Start paragraph describing an argument to a library procedure.
27 '\" type is type of argument (int, etc.), in/out is either "in", "out",
28 '\" or "in/out" to describe whether procedure reads or modifies arg,
29 '\" and indent is equivalent to second arg of .IP (shouldn't ever be
30 '\" needed; use .AS below instead)
33 '\" Give maximum sizes of arguments for setting tab stops. Type and
34 '\" name are examples of largest possible arguments that will be passed
35 '\" to .AP later. If args are omitted, default tab stops are used.
38 '\" Start box enclosure. From here until next .BE, everything will be
39 '\" enclosed in one large box.
42 '\" End of box enclosure.
45 '\" Begin code excerpt.
50 '\" .VS ?version? ?br?
51 '\" Begin vertical sidebar, for use in marking newly-changed parts
52 '\" of man pages. The first argument is ignored and used for recording
53 '\" the version when the .VS was added, so that the sidebars can be
54 '\" found and removed when they reach a certain age. If another argument
55 '\" is present, then a line break is forced before starting the sidebar.
58 '\" End of vertical sidebar.
61 '\" Begin an indented unfilled display.
64 '\" End of indented unfilled display.
67 '\" Start of list of standard options for a Tk widget. The
68 '\" options follow on successive lines, in four columns separated
72 '\" End of list of standard options for a Tk widget.
74 '\" .OP cmdName dbName dbClass
75 '\" Start of description of a specific option. cmdName gives the
76 '\" option's name as specified in the class command, dbName gives
77 '\" the option's name in the option database, and dbClass gives
78 '\" the option's class in the option database.
81 '\" Print arg1 underlined, then print arg2 normally.
83 '\" RCS: @(#) $Id: man.macros,v 1.1.1.1 2009/05/09 16:27:42 pcmacdon Exp $
85 '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
89 '\" # Start an argument description
93 . ie !"\\$2"" .TP \\n()Cu
98 \&\\$1 \\fI\\$2\\fP (\\$3)
111 '\" # define tabbing values for .AP
114 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
117 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
118 .nr )C \\n()Bu+\\w'(in/out)'u+2n
120 .AS Tcl_Interp Tcl_CreateInterp in/out
121 '\" # BS - start boxed text
122 '\" # ^y = starting y location
130 .if n \l'\\n(.lu\(ul'
133 '\" # BE - end boxed text (draw box now)
138 .ie n \l'\\n(^lu\(ul'
140 .\" Draw four-sided box normally, but don't draw top of
141 .\" box if the box started on an earlier page.
143 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
146 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
153 '\" # VS - start vertical sidebar
154 '\" # ^Y = starting y location
155 '\" # ^v = 1 (for troff; for nroff this doesn't matter)
159 .ie n 'mc \s12\(br\s0
162 '\" # VE - end of vertical sidebar
170 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
177 '\" # Special macro to handle page bottom: finish off current
178 '\" # box/sidebar if in box/sidebar mode, then invoked standard
179 '\" # page bottom macro.
186 .\" Draw three-sided box if this is the box's first page,
187 .\" draw two sides but no top otherwise.
188 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
189 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
192 .nr ^x \\n(^tu+1v-\\n(^Yu
193 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
206 '\" # DS - begin display
212 '\" # DE - end display
218 '\" # SO - start of list of standard options
220 .SH "STANDARD OPTIONS"
226 '\" # SE - end of list of standard options
231 See the \\fBoptions\\fR manual entry for details on the standard options.
233 '\" # OP - start of full description for a single option
238 Command-Line Name: \\fB\\$1\\fR
239 Database Name: \\fB\\$2\\fR
240 Database Class: \\fB\\$3\\fR
244 '\" # CS - begin code excerpt
252 '\" # CE - end code excerpt
262 .TH vector n 2.5 BLT "BLT Built-In Commands"
264 '\" Note: do not modify the .SH NAME line immediately below!
266 vector \- Vector data type for Tcl
268 \fBvector configure \fIoption value ...\fR
270 \fBvector create \fIvecName \fR?\fIvecName\fR...? ?\fIswitches\fR?
272 \fBvector destroy \fIvecName \fR?\fIvecName\fR...?
274 \fBvector expr \fIexpression\fR
276 \fBvector names \fR?\fIpattern\fR...?
278 \fBvector op\fR \fIoperation vecName\fR ?\fIarg\fR?...
281 The \fBvector\fR command creates a vector of floating point
282 values. The vector's components can be manipulated in three ways:
283 through a Tcl array variable, a Tcl command, or the C API.
285 A vector is simply an ordered set of numbers. The components of a
286 vector are real numbers, indexed by counting numbers.
288 Vectors are common data structures for many applications. For
289 example, a graph may use two vectors to represent the X-Y
290 coordinates of the data plotted. The graph will automatically
291 be redrawn when the vectors are updated or changed. By using vectors,
293 data analysis from the graph widget. This makes it easier, for
294 example, to add data transformations, such as splines. It's possible
295 to plot the same data to in multiple graphs, where each graph presents
296 a different view or scale of the data.
298 You could try to use Tcl's associative arrays as vectors. Tcl arrays
299 are easy to use. You can access individual elements randomly by
300 specifying the index, or the set the entire array by providing a list
301 of index and value pairs for each element. The disadvantages of
302 associative arrays as vectors lie in the fact they are implemented as
306 There's no implied ordering to the associative arrays. If you used
307 vectors for plotting, you would want to insure the second component
308 comes after the first, an so on. This isn't possible since arrays
309 are actually hash tables. For example, you can't get a range of
310 values between two indices. Nor can you sort an array.
313 Arrays consume lots of memory when the number of elements becomes
314 large (tens of thousands). This is because each element's index and
315 value are stored as strings in the hash table.
318 The C programming interface is unwieldy. Normally with vectors, you
319 would like to view the Tcl array as you do a C array, as an array of
320 floats or doubles. But with hash tables, you must convert both the
321 index and value to and from decimal strings, just to access
322 an element in the array. This makes it cumbersome to perform operations on
323 the array as a whole.
325 The \fBvector\fR command tries to overcome these disadvantages while
326 still retaining the ease of use of Tcl arrays. The \fBvector\fR
327 command creates both a new Tcl command and associate array which are
328 linked to the vector components. You can randomly access vector
329 components though the elements of array. Not all indices are
330 generated for the array, so printing the array (using the \fBparray\fR
331 procedure) does not print out all the component values. You can use
332 the Tcl command to access the array as a whole. You can copy, append,
333 or sort vector using its command. If you need greater performance, or
334 customized behavior, you can write your own C code to manage vectors.
336 You create vectors using the \fBvector\fR command and its \fBcreate\fR
339 # Create a new vector.
342 This creates a new vector named \fBy\fR. It has fifty components, by
343 default, initialized to \fB0.0\fR. In addition, both a Tcl command
344 and array variable, both named \fBy\fR, are created. You can use
345 either the command or variable to query or modify components of the
348 # Set the first value.
350 puts "y has [y length] components"
352 The array \fBy\fR can be used to read or set individual components of
353 the vector. Vector components are indexed from zero. The array index
354 must be a number less than the number of components. For example,
355 it's an error if you try to set the 51st element of \fBy\fR.
357 # This is an error. The vector only has 50 components.
360 You can also specify a range of indices using a colon (:) to separate
361 the first and last indices of the range.
363 # Set the first six components of y
366 If you don't include an index, then it will default to the first
367 and/or last component of the vector.
369 # Print out all the components of y
372 There are special non-numeric indices. The index \fBend\fR, specifies
373 the last component of the vector. It's an error to use this index if
374 the vector is empty (length is zero). The index \fB++end\fR can be
375 used to extend the vector by one component and initialize it to a specific
376 value. You can't read from the array using this index, though.
378 # Extend the vector by one component.
381 The other special indices are \fBmin\fR and \fBmax\fR. They return the
382 current smallest and largest components of the vector.
384 # Print the bounds of the vector
385 puts "min=$y(min) max=$y(max)"
387 To delete components from a vector, simply unset the corresponding
388 array element. In the following example, the first component of
389 \fBy\fR is deleted. All the remaining components of \fBy\fR will be
390 moved down by one index as the length of the vector is reduced by
393 # Delete the first component
395 puts "new first element is $y(0)"
397 The vector's Tcl command can also be used to query or set the vector.
399 # Create and set the components of a new vector
401 x set { 0.02 0.04 0.06 0.08 0.10 0.12 0.14 0.16 0.18 0.20 }
403 Here we've created a vector \fBx\fR without a initial length specification.
404 In this case, the length is zero. The \fBset\fR operation resets the vector,
405 extending it and setting values for each new component.
407 There are several operations for vectors. The \fBrange\fR operation
408 lists the components of a vector between two indices.
410 # List the components
411 puts "x = [x range 0 end]"
413 You can search for a particular value using the \fBsearch\fR
414 operation. It returns a list of indices of the components with the
415 same value. If no component has the same value, it returns \fB""\fR.
417 # Find the index of the biggest component
418 set indices [x search $x(max)]
420 Other operations copy, append, or sort vectors. You can append
421 vectors or new values onto an existing vector with the \fBappend\fR
424 # Append assorted vectors and values to x
425 x append x2 x3 { 2.3 4.5 } x4
427 The \fBsort\fR operation sorts the vector. If any additional vectors
428 are specified, they are rearranged in the same order as the vector.
429 For example, you could use it to sort data points represented by x and
432 # Sort the data points
435 The vector \fBx\fR is sorted while the components of \fBy\fR are
436 rearranged so that the original x,y coordinate pairs are retained.
438 The \fBexpr\fR operation lets you perform arithmetic on vectors.
439 The result is stored in the vector.
441 # Add the two vectors and a scalar
445 When a vector is modified, resized, or deleted, it may trigger
446 call-backs to notify the clients of the vector. For example, when a
447 vector used in the \fBgraph\fR widget is updated, the vector
448 automatically notifies the widget that it has changed. The graph can
449 then redrawn itself at the next idle point. By default, the
450 notification occurs when Tk is next idle. This way you can modify the
451 vector many times without incurring the penalty of the graph redrawing
452 itself for each change. You can change this behavior using the
453 \fBnotify\fR operation.
455 # Make vector x notify after every change
461 # Force notification now
464 # Set Tcl callback for update of Tktable widget .t.
465 x notify callback {.t conf -padx [.t cget -padx]; .t reread}
468 To delete a vector, use the \fBvector delete\fR command.
469 Both the vector and its corresponding Tcl command are destroyed.
474 The psuedo vector \fBlast\fR can be used at the end of an
475 expression to implement running totals.
476 During execution it resolves to the result from the previous
477 vector element evaluation.
484 T expr S+last; # Running total
487 Vectors are created using the \fBvector create\fR operation.
488 Th \fBcreate\fR operation can be invoked in one of three forms:
490 \fBvector create \fIvecName\fR
491 This creates a new vector \fIvecName\fR which initially has no components.
493 \fBvector create \fIvecName\fR(\fIsize\fR)
494 This second form creates a new vector which will contain \fIsize\fR
495 number of components. The components will be indexed starting from
496 zero (0). The default value for the components is \fB0.0\fR.
498 \fBvector create \fIvecName\fR(\fIrows,columns\fR)
499 This form allows creation of a matrix with the specified columns and
500 \fIrows*columns\fR elements.
501 See the \fImatrix\fR section for more details.
503 \fBvector create \fIvecName\fR(\fIfirst\fR:\fIlast\fR)
504 The last form creates a new vector of indexed \fIfirst\fR through
505 \fIlast\fR. \fIFirst\fR and \fIlast\fR can be any integer value
506 so long as \fIfirst\fR is less than \fIlast\fR.
508 Vector names must start with a letter and consist of letters, digits,
511 # Error: must start with letter
514 You can automatically generate vector names using the
515 "\fB#auto\fR" vector name. The \fBcreate\fR operation will generate a
518 set vec [vector create #auto]
519 puts "$vec has [$vec length] components"
522 Vectors are indexed by integers. You can access the individual vector
523 components via its array variable or Tcl command. The string
524 representing the index can be an integer, a numeric expression, a
525 range, or a special keyword.
527 The index must lie within the current range of the vector, otherwise
528 an an error message is returned. Normally the indices of a vector
529 are start from 0. But you can use the \fBoffset\fR operation to
530 change a vector's indices on-the-fly.
536 When \fImatrix numcols\fR is > 1, 2D indexes are supported using
539 vecName matrix numcols 3
542 You can also use numeric expressions as indices. The result
543 of the expression must be an integer value.
546 set vecName($n+3) 50.2
548 The following special non-numeric indices are available: \fBmin\fR, \fBmax\fR, \fBend\fR, and
551 puts "min = $vecName($min)"
552 set vecName(end) -1.2
554 The indices \fBmin\fR and \fBmax\fR will return the minimum and maximum
555 values of the vector. Also available are: \fBprod\fR, \fBsum\fR,
557 The index \fBend\fR returns the value of the
558 last component in the vector.
559 he index \fBend,0\fR returns the value of the
560 last row in column 0 of the vector.
561 The index \fB++end\fR is used to append
562 new value onto the vector. It automatically extends the vector by
563 numcols and sets its value.
565 # Append an new component to the end
566 set vecName(++end) 3.2
568 A range of indices can be indicated by a colon (:).
570 # Set the first six components to 1.0
573 If no index is supplied the first or last component is assumed.
575 # Print the values of all the components
578 .SH VECTOR OPERATIONS
580 \fBvector configure \fI? -flush bool -watchunset bool -oldcreate bool -maxsize int -novariable bool -nocommand bool?\fR
581 The \fBconfigure\fR operation sets the default options used
582 in creating vectors: these options are global to the interpreter.
583 The \fI\-maxsize\fR option, when non-zero, limits creation size.
584 The \fI\-oldcreate\fR enable the creation shortcut: \fBvector vec1 vec2 ...\fR.
585 See the create command for details on the others.
586 By default, these are all disabled or zero.
589 \fBvector create \fIvecName\fR?(\fIsize\fR)?... \fR?\fIswitches\fR?
590 The \fBcreate\fR operation creates a new vector \fIvecName\fR. The
591 \fIsize\fR may be an integer, a START:END range or ROW,COL (see matrix).
593 Tcl command and array variable called \fIvecName\fR. The
594 name \fIvecName\fR must be unique, so another Tcl command or array
595 variable can not already exist in the current scope. You may access the
596 components of the vector using the variable. If you change a value in
597 the array, or unset an array element, the vector is updated to reflect
598 the changes. When the variable \fIvecName\fR is unset, the vector and
599 its Tcl command are also destroyed.
601 The vector has optional switches that affect how the vector is created. They
605 \fB\-variable \fIvarName\fR
606 Specifies the name of a Tcl variable to be mapped to the vector. If
607 the variable already exists, it is first deleted, then recreated.
608 If \fIvarName\fR is the empty string, then no variable will be mapped.
609 You can always map a variable back to the vector using the vector's
610 \fBvariable\fR operation.
612 \fB\-command \fIcmdName\fR
613 Maps a Tcl command to the vector. The vector can be accessed using
614 \fIcmdName\fR and one of the vector instance operations.
615 A Tcl command by that name cannot already exist.
616 If \fIcmdName\fR is the empty string, no command mapping
619 \fB\-watchunset \fIboolean\fR
620 Indicates that the vector should automatically delete itself if
621 the variable associated with the vector is unset. By default,
622 the vector will not be deleted. This is different from previous
623 releases. Set \fIboolean\fR to "true" to get the old behavior.
625 \fB\-flush \fIboolean\fR
626 Indicates that the vector should automatically flush the cached
627 variable elements which unsets all the elements of the Tcl array
628 variable associated with the vector, freeing memory associated
629 with the variable. This includes both the hash table and the hash keys.
630 The down side is that this effectively flushes the caching of vector
631 elements in the array. This means that the subsequent reads
632 of the array will require a decimal to string conversion.
633 By default, flushing is disabled.
636 \fBvector destroy \fIvecName\fR \fR?\fIvecName...\fR?
639 \fBvector expr \fIexpression\fR
641 All binary operators take vectors as operands (remember that numbers
642 are treated as one-component vectors).The exact action of binary
643 operators depends upon the length of the second operand. If the
644 second operand has only one component, then each element of the first
645 vector operand is computed by that value. For example, the expression
646 "x * 2" multiples all elements of the vector x by 2. If the second
647 operand has more than one component, both operands must be the same
648 length. Each pair of corresponding elements are computed. So "x + y"
649 adds the the first components of x and y together, the second, and so on.
651 The valid operators are listed below, grouped in decreasing order
655 Unary minus and logical NOT. The unary minus flips the sign of each
656 component in the vector. The logical not operator returns a vector of
657 whose values are 0.0 or 1.0. For each non-zero component 1.0 is returned,
664 Multiply, divide, remainder.
670 Left and right shift. Circularly shifts the values of the vector
672 \fB<\0\0>\0\0<=\0\0>=\fR
673 Boolean less, greater, less than or equal, and greater than or equal.
674 Each operator returns a vector of ones and zeros. If the condition is true,
675 1.0 is the component value, 0.0 otherwise.
678 Boolean equal and not equal.
679 Each operator returns a vector of ones and zeros. If the condition is true,
680 1.0 is the component value, 0.0 otherwise.
683 Logical AND. Produces a 1 result if both operands are non-zero, 0 otherwise.
686 Logical OR. Produces a 0 result if both operands are zero, 1 otherwise.
688 \fIx\fB?\fIy\fB:\fIz\fR
689 If-then-else, as in C.
692 See the C manual for more details on the results produced by each
693 operator. All of the binary operators group left-to-right within the
694 same precedence level.
696 Several mathematical functions are supported for vectors. Each of
697 the following functions invokes the math library function of the same name;
698 see the manual entries for the library functions for details on what
699 they do. The operation is applied to all elements of the vector
700 returning the results. All functions take a vector operand.
701 If no vector operand is used in the call, the current
702 vector is assumed. eg.
706 aVec expr {2*abs(aVec)-1}
709 vector expr {2*row()} ; # ERROR!
713 \fBacos\fR \fBcos\fR \fBhypot\fR \fBsinh\fR
714 \fBasin\fR \fBcosh\fR \fBlog\fR \fBsqrt\fR
715 \fBatan\fR \fBexp\fR \fBlog10\fR \fBtan\fR
716 \fBceil\fR \fBfloor\fR \fBsin\fR \fBtanh\fR
718 Additional functions are:
721 Returns the absolute value of each component.
724 Returns a vector of non-negative values uniformly distributed
725 between [0.0, 1.0) using \fIdrand48\fR.
726 The seed comes from the internal clock of the machine or may be
727 set manual with the srandom function.
730 Rounds each component of the vector.
733 Initializes the random number generator using \fIsrand48\fR.
734 The high order 32-bits are set using the integral portion of the first
735 vector component. All other components are ignored. The low order 16-bits
736 are set to an arbitrary value.
738 The following functions return a single value.
741 Returns the average deviation (defined as the sum of the absolute values
742 of the differences between component and the mean, divided by the length
746 Returns the degree of peakedness (fourth moment) of the vector.
749 Returns the number of components in the vector.
752 Returns the vector's maximum value.
755 Returns the mean value of the vector.
758 Returns the median of the vector.
761 Returns the vector's minimum value.
764 Returns the first quartile of the vector.
767 Returns the third quartile of the vector.
770 Returns the product of the components.
773 Returns the standard deviation (defined as the square root of the variance)
777 Returns the skewness (or third moment) of the vector. This characterizes
778 the degree of asymmetry of the vector about the mean.
781 Returns the sum of the components.
784 Returns the variance of the vector. The sum of the squared differences
785 between each component and the mean is computed. The variance is
786 the sum divided by the length of the vector minus 1.
788 This last set of functions returns a vector of the same length as the argument.
791 Returns vector with elements in reversed order.
794 Scales the values of the vector to lie in the range [0.0..1.0].
797 Psuedo function to get the current row.
800 Returns the vector components sorted in ascending order.
803 This is the only function taking a second arg.
804 It provides a version of \fInvec\fR shifted by N places.
805 When N is a scalar or vector with only one element,
806 shift fills vacant area with 0. Otherwise the second element of
807 \fInVec\fR is used for the fill value.
808 One use for this is providing running totals.
811 \fBvector names \fR?\fIpattern\fR?
812 Return names of all defined vectors.
815 \fBvector op\fR \fIoperation vecName\fR ?\fIarg\fR?...
816 Invoke instance operation. Supported operations are defined in the next section.
817 Op is the only way to invoke instance operation sub-commands
818 when -command is defined as empty in
819 a vector. It also allows writing vector code that is checkable
820 by a syntax checkers. eg.
829 .SH INSTANCE OPERATIONS
830 You can also use the vector's Tcl command to query or modify it. The
833 \fIvecName \fIoperation\fR \fR?\fIarg\fR?...
835 Note this is equivalent to the form:
837 \fBvector op\fR \fIoperation vecName\fR ?\fIarg\fR?...
839 Both \fIoperation\fR and its arguments determine the exact behavior of
840 the command. The operations available for vectors are listed below.
842 \fIvecName \fB+\fR \fIitem\fR
843 \fIvecName \fB-\fR \fIitem\fR
844 \fIvecName \fB*\fR \fIitem\fR
845 \fIvecName \fB/\fR \fIitem\fR
846 Perform binary op and return result as a list.
848 \fIvecName \fBappend\fR \fIitem\fR ?\fIitem\fR?...
849 Appends the component values from \fIitem\fR to \fIvecName\fR.
850 \fIItem\fR can be either the name of a vector or a list of numeric
853 \fIvecName \fBbinread\fR \fIchannel\fR ?\fIlength\fR? ?\fIswitches\fR?
854 Reads binary values from a Tcl channel. Values are either appended
855 to the end of the vector or placed at a given index (using the
856 \fB\-at\fR option), overwriting existing values. Data is read until EOF
857 is found on the channel or a specified number of values \fIlength\fR
858 are read (note that this is not necessarily the same as the number of
859 bytes). The following switches are supported:
863 Swap bytes and words. The default endian is the host machine.
866 New values will start at vector index \fIindex\fR. This will
867 overwrite any current values.
869 \fB\-format\fR \fIformat\fR
870 Specifies the format of the data. \fIFormat\fR can be one of the
871 following: "i1", "i2", "i4", "i8", "u1, "u2", "u4", "u8", "r4",
872 "r8", or "r16". The number indicates the number of bytes
873 required for each value. The letter indicates the type: "i" for signed,
874 "u" for unsigned, "r" or real. The default format is "r16".
877 \fIvecName \fBbinwrite\fR \fIchannel\fR ?\fIlength\fR? ?\fI\-at index\fR?
878 Like \fBbinread\fR, but writes data.
880 \fIvecName \fBclear\fR
881 Clears the element indices from the array variable associated with
882 \fIvecName\fR. This doesn't affect the components of the vector. By
883 default, the number of entries in the Tcl array doesn't match the
884 number of components in the vector. This is because its too expensive
885 to maintain decimal strings for both the index and value for each
886 component. Instead, the index and value are saved only when you read
887 or write an element with a new index. This command removes the index
888 and value strings from the array. This is useful when the vector is
891 \fIvecName \fBdelete\fR \fIindex\fR ?\fIindex\fR?...
892 Deletes the \fIindex\fRth component from the vector \fIvecName\fR.
893 \fIIndex\fR is the index of the element to be deleted. This is the
894 same as unsetting the array variable element \fIindex\fR. The vector
895 is compacted after all the indices have been deleted.
897 \fIvecName \fBdup\fR \fIdestName\fR
898 Copies \fIvecName\fR to \fIdestName\fR. \fIDestName\fR is the name of a
899 destination vector. If a vector \fIdestName\fR already exists, it is
900 overwritten with the components of \fIvecName\fR. Otherwise a
901 new vector is created.
903 \fIvecName \fBexpr\fR \fIexpression\fR
904 Computes the expression and resets the values of the vector accordingly.
905 Both scalar and vector math operations are allowed. All values in
906 expressions are either real numbers or names of vectors. All numbers
907 are treated as one component vectors.
909 \fIvecName \fBindex\fR \fIindex\fR ?\fIvalue\fR?...
910 Get/set individual vector values. This provides element
911 updating when \fI\-variable\fR is set to empty.
913 \fIvecName \fBinsert\fR \fIindex\fR \fIitem\fR ?\fIitem\fR?...
914 Inserts the component values from \fIitem\fR to \fIvecName\fR at
915 \fIindex\fR \fIItem\fR can be either the name of a vector or
916 a list of numeric values.
918 \fIvecName \fBlength\fR ?\fInewSize\fR?
919 Queries or resets the number of components in \fIvecName\fR.
920 \fINewSize\fR is a number specifying the new size of the vector. If
921 \fInewSize\fR is smaller than the current size of \fIvecName\fR,
922 \fIvecName\fR is truncated. If \fInewSize\fR is greater, the vector
923 is extended and the new components are initialized to \fB0.0\fR. If
924 no \fInewSize\fR argument is present, the current length of the vector
927 \fIvecName \fBmatrix \fI ...\fR
928 Matrix provides a 2D array view into 1D data. It provides indexing operations
929 in ROW,COL form making it suitable for use with TkTable.
930 Data storage remains unchanged: vectors are still just a single long array.
931 For example, here are two ways to create a 3 column by 10 row matrix:
934 vector create aVec(10,3)
935 vector create bVec(30)
936 bVec matrix numcols 3
939 aVec append {5 6 7}; # aVec now has 11 rows.
940 aVec append 1 2; # Now aVec has 13 rows!
943 Note that data is appended only in increments of numcols.
944 Elements 0-2 make up the first row, 3-5 the second, etc.
945 Elements will appear only in increments of the column size.
948 \fIvecName \fBmatrix copy \fIdstcolumn\fR \fIsrccolumn\fR \fI?srcVec?\fR
949 Copy a column of element values
950 to column \fIdstcolumn\fR from \fIsrccolumn\fR.
951 If vector \fIsrcVec\fR is given, and not the same as \fIvecName\fR, the
952 columns numbers must be different.
953 If the \fIsrcVec\fR column is longer, \fIvecName\fR will be extended.
954 If shorter, remaining destination values are not overwritten.
956 \fIvecName \fBmatrix delete \fIcolumn\fR.
957 Delete elements in a column.
958 Note that \fBnumcols\fR, which must be greater than 1, will be decremented.
960 \fIvecName \fBmatrix get \fIcolumn\fR
961 Get the element in a column: this number must be
962 less than \fBnumcols\fR.
963 Note that \fBnumcols\fR must be non-zero.
965 \fIvecName \fBmatrix insert \fIcolumn\fR \fI?initvalue?\fR .
966 Insert a new column of elements at column (default 0).
967 The new column is initialized
968 with \fIinitvalue\fR, or \fI0.0\fR if not specified.
969 Note that \fBnumcols\fR will be incremented.
971 \fIvecName \fBmatrix multiply \fIsrcVec\fR ?\fIdstVec\fR?
972 Perform matrix multiplication using \fBsrcVec\fR,
973 placing results either in \fBdstVec\fR, or returned as a list.
974 The numrows of \fIsrcVec\fR must equal numcols in
975 \fIvecName\fR. One application for multiply is coordinate transformation.
977 \fIvecName \fBmatrix numcols \fI?size?\fR
978 Get or set the number of columns for a vectors data. Values >1 enable
979 array variables to accept 2d matrix indexes.
980 For example with a numcols of 10, \fB$vec1(1,2)\fR refers to the
981 13th element in the vector. A vectors size is also constrained
982 to multiples of numcols, as is it's offset.
983 By default, numcols is 1.
985 \fIvecName \fBmatrix numrows \fI?size?\fR
986 Get or set the length of rows in a columns for a vector.
987 By default, this is just the \fIvector length/numcols\fR.
988 Setting this value simply provides a convenient way to increase or decrease
989 the vector size by multiples of \fInumcols\fR.
991 \fIvecName \fBmatrix set \fIcolumn\fR \fI?valuelist?\fR
992 Set value elements in a column: this number must be
993 less than \fBnumcols\fR. The \fIvaluelist\fR is a list values.
994 If this list is shorter than the column, it's last
995 value is used for all remaining columns. The column gets set to
996 the values of \fIitem\fR, or \fI0.0\fR by default.
998 \fIvecName \fBmatrix shift \fIcolumn\fR \fIamount\fR ?\fIstartoffset\fR?
999 Shifts the values of a column by integer in\fIamount\fR. A negative
1000 value shifts upward.
1001 The \fIstartoffset\fR indicates where to start shifting from.
1003 \fIvecName \fBmatrix sort \fIcolumn\fR \fI?-reverse?\fR
1004 Sort the vector by the given column.
1006 \fIvecName \fBmatrix transpose\fR
1007 Transpose all columns with rows in matrix.
1008 Note that this is a no-op if \fBnumcols\fR is 1. Otherwise,
1009 numcols will change to \fBvectorLength/numcols\fR.
1012 \fIvecName \fBmerge\fR \fIsrcName\fR ?\fIsrcName\fR?...
1013 Merges the named vectors into a single vector. The resulting
1014 vector is formed by merging the components of each source vector
1015 one index at a time.
1017 \fIvecName \fBnotify\fR ?\fIkeyword\fR? ?\fIscript\fR?
1018 Queries or controls how vector clients are notified of changes
1019 to the vector. Also allows setting a notifier callback.
1020 The exact behavior is determined by \fIkeyword\fR.
1024 Indicates that clients are to be notified immediately whenever the
1028 Indicates that no clients are to be notified.
1031 Indicates that clients are to be notified at the next idle point
1032 whenever the vector is updated.
1035 If any client notifications is currently pending, they are notified
1039 Cancels pending notifications of clients using the vector.
1042 Returns \fB1\fR if a client notification is pending, and \fB0\fR otherwise.
1044 \fBcallback\fR ?\fIscript\fR?
1045 Query or set a Tcl callback script that is evaluated when a vector is updated.
1048 \fIvecName \fBpopulate\fR \fIdestName\fR ?\fIdensity\fR?
1049 Creates a vector \fIdestName\fR which is a superset of \fIvecName\fR.
1050 \fIDestName\fR will include all the components of \fIvecName\fR, in
1051 addition the interval between each of the original components will
1052 contain a \fIdensity\fR number of new components, whose values are
1053 evenly distributed between the original components values. This is
1054 useful for generating abscissas to be interpolated along a spline.
1056 \fIvecName \fBrange\fR \fIfirstIndex\fR ?\fIlastIndex\fR?...
1057 Returns a list of numeric values representing the vector components
1058 between two indices. Both \fIfirstIndex\fR and \fIlastIndex\fR are
1059 indices representing the range of components to be returned. If
1060 \fIlastIndex\fR is less than \fIfirstIndex\fR, the components are
1061 listed in reverse order.
1063 \fIvecName \fBsearch\fR \fIvalue\fR ?\fIvalue\fR?
1064 Searches for a value or range of values among the components of
1065 \fIvecName\fR. If one \fIvalue\fR argument is given, a list of
1066 indices of the components which equal \fIvalue\fR is returned. If a
1067 second \fIvalue\fR is also provided, then the indices of all
1068 components which lie within the range of the two values are returned.
1069 If no components are found, then \fB""\fR is returned.
1071 \fIvecName \fBset\fR \fIitem\fR
1072 Resets the components of the vector to \fIitem\fR. \fIItem\fR can
1073 be either a list of numeric expressions or another vector.
1075 \fIvecName \fBseq\fR \fIstart\fR ?\fIfinish\fR? ?\fIstep\fR?
1076 Generates a sequence of values starting with the value \fIstart\fR.
1077 \fIFinish\fR indicates the terminating value of the sequence.
1078 The vector is automatically resized to contain just the sequence.
1079 If three arguments are present, \fIstep\fR designates the interval.
1081 With only two arguments (no \fIfinish\fR argument), the sequence will
1082 continue until the vector is filled. With one argument, the interval
1085 \fIvecName \fBsort\fR ?\fB-reverse\fR? ?\fIargName\fR?...
1086 Sorts the vector \fIvecName\fR in increasing order. If the
1087 \fB-reverse\fR flag is present, the vector is sorted in decreasing
1088 order. If other arguments \fIargName\fR are present, they are the
1089 names of vectors which will be rearranged in the same manner as
1090 \fIvecName\fR. Each vector must be the same length as \fIvecName\fR.
1091 You could use this to sort the x vector of a graph, while still
1092 retaining the same x,y coordinate pairs in a y vector.
1094 \fIvecName \fBsplit\fR \fIdstName\fR ?\fIdstName\fR?...
1095 Split the vector into a multiple vectors. The resulting
1096 N vectors each contain the mod-Nth element from source.
1098 \fIvecName \fBvariable\fR \fIvarName\fR
1099 Maps a Tcl variable to the vector, creating another means for
1100 accessing the vector. The variable \fIvarName\fR can't already
1101 exist. This overrides any current variable mapping the vector
1105 You can create, modify, and destroy vectors from C code, using
1107 You need to include the header file \fBblt.h\fR. It contains the
1108 definition of the structure \fBBlt_Vector\fR, which represents the
1109 vector. It appears below.
1112 double *\fIvalueArr\fR;
1113 int \fInumValues\fR;
1114 int \fIarraySize\fR;
1115 double \fImin\fR, \fImax\fR;
1118 The field \fIvalueArr\fR points to memory holding the vector
1119 components. The components are stored in a double precision array,
1120 whose size size is represented by \fIarraySize\fR. \fINumValues\fR is
1121 the length of vector. The size of the array is always equal to or
1122 larger than the length of the vector. \fIMin\fR and \fImax\fR are
1123 minimum and maximum component values.
1124 .SH LIBRARY ROUTINES
1125 The following routines are available from C to manage vectors.
1126 Vectors are identified by the vector name.
1128 \fBBlt_CreateVector\fR
1133 int \fBBlt_CreateVector\fR (\fIinterp\fR, \fIvecName\fR, \fIlength\fR, \fIvecPtrPtr\fR)
1135 Tcl_Interp *\fIinterp\fR;
1136 char *\fIvecName\fR;
1138 Blt_Vector **\fIvecPtrPtr\fR;
1143 Creates a new vector \fIvecName\fR\fR with a length of \fIlength\fR.
1144 \fBBlt_CreateVector\fR creates both a new Tcl command and array
1145 variable \fIvecName\fR. Neither a command nor variable named
1146 \fIvecName\fR can already exist. A pointer to the vector is
1147 placed into \fIvecPtrPtr\fR.
1150 Returns \fBTCL_OK\fR if the vector is successfully created. If
1151 \fIlength\fR is negative, a Tcl variable or command \fIvecName\fR
1152 already exists, or memory cannot be allocated for the vector, then
1153 \fBTCL_ERROR\fR is returned and \fIinterp->result\fR will contain an
1158 \fBBlt_DeleteVectorByName\fR
1163 int \fBBlt_DeleteVectorByName\fR (\fIinterp\fR, \fIvecName\fR)
1165 Tcl_Interp *\fIinterp\fR;
1166 char *\fIvecName\fR;
1171 Removes the vector \fIvecName\fR. \fIVecName\fR is the name of a vector
1172 which must already exist. Both the Tcl command and array variable
1173 \fIvecName\fR are destroyed. All clients of the vector will be notified
1174 immediately that the vector has been destroyed.
1177 Returns \fBTCL_OK\fR if the vector is successfully deleted. If
1178 \fIvecName\fR is not the name a vector, then \fBTCL_ERROR\fR is returned
1179 and \fIinterp->result\fR will contain an error message.
1183 \fBBlt_DeleteVector\fR
1188 int \fBBlt_DeleteVector\fR (\fIvecPtr\fR)
1190 Blt_Vector *\fIvecPtr\fR;
1195 Removes the vector pointed to by \fIvecPtr\fR. \fIVecPtr\fR is a
1196 pointer to a vector, typically set by \fBBlt_GetVector\fR or
1197 \fBBlt_CreateVector\fR. Both the Tcl command and array variable of
1198 the vector are destroyed. All clients of the vector will be notified
1199 immediately that the vector has been destroyed.
1202 Returns \fBTCL_OK\fR if the vector is successfully deleted. If
1203 \fIvecName\fR is not the name a vector, then \fBTCL_ERROR\fR is returned
1204 and \fIinterp->result\fR will contain an error message.
1213 int \fBBlt_GetVector\fR (\fIinterp\fR, \fIvecName\fR, \fIvecPtrPtr\fR)
1215 Tcl_Interp *\fIinterp\fR;
1216 char *\fIvecName\fR;
1217 Blt_Vector **\fIvecPtrPtr\fR;
1222 Retrieves the vector \fIvecName\fR. \fIVecName\fR is the name of a
1223 vector which must already exist. \fIVecPtrPtr\fR will point be set to
1224 the address of the vector.
1227 Returns \fBTCL_OK\fR if the vector is successfully retrieved. If
1228 \fIvecName\fR is not the name of a vector, then \fBTCL_ERROR\fR is
1229 returned and \fIinterp->result\fR will contain an error message.
1233 \fBBlt_ResetVector\fR
1239 int \fBBlt_ResetVector\fR (\fIvecPtr\fR, \fIdataArr\fR,
1240 \fInumValues\fR, \fIarraySize\fR, \fIfreeProc\fR)
1242 Blt_Vector *\fIvecPtr\fR;
1243 double *\fIdataArr\fR;
1244 int *\fInumValues\fR;
1245 int *\fIarraySize\fR;
1246 Tcl_FreeProc *\fIfreeProc\fR;
1251 Resets the components of the vector pointed to by \fIvecPtr\fR.
1252 Calling \fBBlt_ResetVector\fR will trigger the vector to dispatch
1253 notifications to its clients. \fIDataArr\fR is the array of doubles
1254 which represents the vector data. \fINumValues\fR is the number of
1255 elements in the array. \fIArraySize\fR is the actual size of the array
1256 (the array may be bigger than the number of values stored in
1257 it). \fIFreeProc\fP indicates how the storage for the vector component
1258 array (\fIdataArr\fR) was allocated. It is used to determine how to
1259 reallocate memory when the vector is resized or destroyed. It must be
1260 \fBTCL_DYNAMIC\fR, \fBTCL_STATIC\fR, \fBTCL_VOLATILE\fR, or a pointer
1261 to a function to free the memory allocated for the vector array. If
1262 \fIfreeProc\fR is \fBTCL_VOLATILE\fR, it indicates that \fIdataArr\fR
1263 must be copied and saved. If \fIfreeProc\fR is \fBTCL_DYNAMIC\fR, it
1264 indicates that \fIdataArr\fR was dynamically allocated and that Tcl
1265 should free \fIdataArr\fR if necessary. \fBStatic\fR indicates that
1266 nothing should be done to release storage for \fIdataArr\fR.
1269 Returns \fBTCL_OK\fR if the vector is successfully resized. If
1270 \fInewSize\fR is negative, a vector \fIvecName\fR does not exist, or
1271 memory cannot be allocated for the vector, then \fBTCL_ERROR\fR is
1272 returned and \fIinterp->result\fR will contain an error message.
1276 \fBBlt_ResizeVector\fR
1281 int \fBBlt_ResizeVector\fR (\fIvecPtr\fR, \fInewSize\fR)
1283 Blt_Vector *\fIvecPtr\fR;
1289 Resets the length of the vector pointed to by \fIvecPtr\fR to
1290 \fInewSize\fR. If \fInewSize\fR is smaller than the current size of
1291 the vector, it is truncated. If \fInewSize\fR is greater, the vector
1292 is extended and the new components are initialized to \fB0.0\fR.
1293 Calling \fBBlt_ResetVector\fR will trigger the vector to dispatch
1297 Returns \fBTCL_OK\fR if the vector is successfully resized. If
1298 \fInewSize\fR is negative or memory can not be allocated for the vector,
1299 then \fBTCL_ERROR\fR is returned and \fIinterp->result\fR will contain
1303 \fBBlt_VectorExists\fR
1308 int \fBBlt_VectorExists\fR (\fIinterp\fR, \fIvecName\fR)
1310 Tcl_Interp *\fIinterp\fR;
1311 char *\fIvecName\fR;
1316 Indicates if a vector named \fIvecName\fR exists in \fIinterp\fR.
1319 Returns \fB1\fR if a vector \fIvecName\fR exists and \fB0\fR otherwise.
1323 If your application needs to be notified when a vector changes, it can
1324 allocate a unique \fIclient identifier\fR for itself. Using this
1325 identifier, you can then register a call-back to be made whenever the
1326 vector is updated or destroyed. By default, the call-backs are made at
1327 the next idle point. This can be changed to occur at the time the
1328 vector is modified. An application can allocate more than one
1329 identifier for any vector. When the client application is done with
1330 the vector, it should free the identifier.
1332 The call-back routine must of the following type.
1336 typedef void (\fBBlt_VectorChangedProc\fR) (Tcl_Interp *\fIinterp\fR,
1338 ClientData \fIclientData\fR, Blt_VectorNotify \fInotify\fR);
1344 \fIClientData\fR is passed to this routine whenever it is called. You
1345 can use this to pass information to the call-back. The \fInotify\fR
1346 argument indicates whether the vector has been updated of destroyed. It
1347 is an enumerated type.
1352 \fBBLT_VECTOR_NOTIFY_UPDATE\fR=1,
1353 \fBBLT_VECTOR_NOTIFY_DESTROY\fR=2
1354 } \fBBlt_VectorNotify\fR;
1359 \fBBlt_AllocVectorId\fR
1364 Blt_VectorId \fBBlt_AllocVectorId\fR (\fIinterp\fR, \fIvecName\fR)
1366 Tcl_Interp *\fIinterp\fR;
1367 char *\fIvecName\fR;
1372 Allocates an client identifier for with the vector \fIvecName\fR.
1373 This identifier can be used to specify a call-back which is triggered
1374 when the vector is updated or destroyed.
1377 Returns a client identifier if successful. If \fIvecName\fR is not
1378 the name of a vector, then \fBNULL\fR is returned and
1379 \fIinterp->result\fR will contain an error message.
1383 \fBBlt_GetVectorById\fR
1388 int \fBBlt_GetVector\fR (\fIinterp\fR, \fIclientId\fR, \fIvecPtrPtr\fR)
1390 Tcl_Interp *\fIinterp\fR;
1391 Blt_VectorId \fIclientId\fR;
1392 Blt_Vector **\fIvecPtrPtr\fR;
1397 Retrieves the vector used by \fIclientId\fR. \fIClientId\fR is a valid
1398 vector client identifier allocated by \fBBlt_AllocVectorId\fR.
1399 \fIVecPtrPtr\fR will point be set to the address of the vector.
1402 Returns \fBTCL_OK\fR if the vector is successfully retrieved.
1406 \fBBlt_SetVectorChangedProc\fR
1411 void \fBBlt_SetVectorChangedProc\fR (\fIclientId\fR, \fIproc\fR, \fIclientData\fR);
1413 Blt_VectorId \fIclientId\fR;
1414 Blt_VectorChangedProc *\fIproc\fR;
1415 ClientData *\fIclientData\fR;
1420 Specifies a call-back routine to be called whenever the vector
1421 associated with \fIclientId\fR is updated or deleted. \fIProc\fR is a
1422 pointer to call-back routine and must be of the type
1423 \fBBlt_VectorChangedProc\fR. \fIClientData\fR is a one-word value to
1424 be passed to the routine when it is invoked. If \fIproc\fR is
1425 \fBNULL\fR, then the client is not notified.
1428 The designated call-back procedure will be invoked when the vector is
1429 updated or destroyed.
1433 \fBBlt_FreeVectorId\fR
1438 void \fBBlt_FreeVectorId\fR (\fIclientId\fR);
1440 Blt_VectorId \fIclientId\fR;
1445 Frees the client identifier. Memory allocated for the identifier
1446 is released. The client will no longer be notified when the
1450 The designated call-back procedure will be no longer be invoked when
1451 the vector is updated or destroyed.
1455 \fBBlt_NameOfVectorId\fR
1460 char *\fBBlt_NameOfVectorId\fR (\fIclientId\fR);
1462 Blt_VectorId \fIclientId\fR;
1467 Retrieves the name of the vector associated with the client identifier
1471 Returns the name of the vector associated with \fIclientId\fR. If
1472 \fIclientId\fR is not an identifier or the vector has been destroyed,
1473 \fBNULL\fR is returned.
1477 \fBBlt_InstallIndexProc\fR
1482 void \fBBlt_InstallIndexProc\fR (\fIindexName\fR, \fIprocPtr\fR)
1484 char *\fIindexName\fR;
1485 Blt_VectorIndexProc *\fIprocPtr\fR;
1490 Registers a function to be called to retrieved the index \fIindexName\fR
1491 from the vector's array variable.
1493 typedef double Blt_VectorIndexProc(Vector *vecPtr);
1495 The function will be passed a pointer to the vector. The function must
1496 return a double representing the value at the index.
1499 The new index is installed into the vector.
1503 The following example opens a file of binary data and stores it in an
1504 array of doubles. The array size is computed from the size of the
1505 file. If the vector "data" exists, calling \fBBlt_VectorExists\fR,
1506 \fBBlt_GetVector\fR is called to get the pointer to the vector.
1507 Otherwise the routine \fBBlt_CreateVector\fR is called to create a new
1508 vector and returns a pointer to it. Just like the Tcl interface, both
1509 a new Tcl command and array variable are created when a new vector is
1510 created. It doesn't make any difference what the initial size of the
1511 vector is since it will be reset shortly. The vector is updated when
1512 \fBlt_ResetVector\fR is called. Blt_ResetVector makes the changes
1513 visible to the Tcl interface and other vector clients (such as a graph
1523 struct stat statBuf;
1524 int numBytes, numValues;
1526 f = fopen("binary.dat", "r");
1527 fstat(fileno(f), &statBuf);
1528 numBytes = (int)statBuf.st_size;
1530 /* Allocate an array big enough to hold all the data */
1531 newArr = (double *)malloc(numBytes);
1532 numValues = numBytes / sizeof(double);
1533 fread((void *)newArr, numValues, sizeof(double), f);
1536 if (Blt_VectorExists(interp, "data")) {
1537 if (Blt_GetVector(interp, "data", &vecPtr) != TCL_OK) {
1541 if (Blt_CreateVector(interp, "data", 0, &vecPtr) != TCL_OK) {
1546 * Reset the vector. Clients will be notified when Tk is idle.
1547 * TCL_DYNAMIC tells the vector to free the memory allocated
1548 * if it needs to reallocate or destroy the vector.
1550 if (Blt_ResetVector(vecPtr, newArr, numValues, numValues,
1551 TCL_DYNAMIC) != TCL_OK) {
1555 .SH "INCOMPATIBILITIES"
1556 In previous versions, if the array variable isn't global
1557 (i.e. local to a Tcl procedure), the vector is automatically
1558 destroyed when the procedure returns.
1561 # Temporary vector x
1568 This has changed. Variables are not automatically destroyed when
1569 their variable is unset. You can restore the old behavior by
1570 setting the "-watchunset" switch.
1573 vector, graph, widget
OSDN Git Service
