Table of Contents

Name

Blt_Vector - Vector data object.

C Language API

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 Blt_Vector, which represents the vector. It appears below.


typedef struct {
double *valueArr;
int numValues;
int arraySize;
double min, max;
} Blt_Vector;

The field valueArr points to memory holding the vector components. The components are stored in a double precision array, whose size size is represented by arraySize. NumValues is the length of vector. The size of the array is always equal to or larger than the length of the vector. Min and max are minimum and maximum component values.

Library Routines

The following routines are available from C to manage vectors. Vectors are identified by the vector name.

Blt_CreateVector

Synopsis:

int Blt_CreateVector (interp, vecName, length, vecPtrPtr)
Tcl_Interp *interp;
char *vecName;
int length;
Blt_Vector **vecPtrPtr;
Description:
Creates a new vector vecName with a length of length. Blt_CreateVector creates both a new Tcl command and array variable vecName. Neither a command nor variable named vecName can already exist. A pointer to the vector is placed into vecPtrPtr.
Results:
Returns TCL_OK if the vector is successfully created. If length is negative, a Tcl variable or command vecName already exists, or memory cannot be allocated for the vector, then TCL_ERROR is returned and interp->result will contain an error message.

Blt_DeleteVectorByName

Synopsis:

int Blt_DeleteVectorByName (interp, vecName)
Tcl_Interp *interp;
char *vecName;
Description:
Removes the vector vecName. VecName is the name of a vector which must already exist. Both the Tcl command and array variable vecName 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 vecName is not the name a vector, then TCL_ERROR is returned and interp->result will contain an error message.

Blt_DeleteVector

Synopsis:

int Blt_DeleteVector (vecPtr)
Blt_Vector *vecPtr;
Description:
Removes the vector pointed to by vecPtr. VecPtr is a pointer to a vector, typically set by Blt_GetVector or Blt_CreateVector. 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 vecName is not the name a vector, then TCL_ERROR is returned and interp->result will contain an error message.

Blt_GetVector

Synopsis:

int Blt_GetVector (interp, vecName, vecPtrPtr)
Tcl_Interp *interp;
char *vecName;
Blt_Vector **vecPtrPtr;
Description:
Retrieves the vector vecName. VecName is the name of a vector which must already exist. VecPtrPtr will point be set to the address of the vector.
Results:
Returns TCL_OK if the vector is successfully retrieved. If vecName is not the name of a vector, then TCL_ERROR is returned and interp->result will contain an error message.

Blt_ResetVector

Synopsis:

int Blt_ResetVector (vecPtr, dataArr,
   numValues, arraySize, freeProc)
Blt_Vector *vecPtr;
double *dataArr;
int *numValues;
int *arraySize;
Tcl_FreeProc *freeProc;
Description:
Resets the components of the vector pointed to by vecPtr. Calling Blt_ResetVector will trigger the vector to dispatch notifications to its clients. DataArr is the array of doubles which represents the vector data. NumValues is the number of elements in the array. ArraySize is the actual size of the array (the array may be bigger than the number of values stored in it). FreeProc indicates how the storage for the vector component array (dataArr) was allocated. It is used to determine how to reallocate memory when the vector 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 freeProc is TCL_VOLATILE, it indicates that dataArr must be copied and saved. If freeProc is TCL_DYNAMIC, it indicates that dataArr was dynamically allocated and that Tcl should free dataArr if necessary. Static indicates that nothing should be done to release storage for dataArr.
Results:
Returns TCL_OK if the vector is successfully resized. If newSize is negative, a vector vecName does not exist, or memory cannot be allocated for the vector, then TCL_ERROR is returned and interp->result will contain an error message.

Blt_ResizeVector

Synopsis:

int Blt_ResizeVector (vecPtr, newSize)
Blt_Vector *vecPtr;
int newSize;
Description:
Resets the length of the vector pointed to by vecPtr to newSize. If newSize is smaller than the current size of the vector, it is truncated. If newSize is greater, the vector is extended and the new components are initialized to 0.0. Calling Blt_ResetVector will trigger the vector to dispatch notifications.
Results:
Returns TCL_OK if the vector is successfully resized. If newSize is negative or memory can not be allocated for the vector, then TCL_ERROR is returned and interp->result will contain an error message.

Blt_VectorExists

Synopsis:

int Blt_VectorExists (interp, vecName)
Tcl_Interp *interp;
char *vecName;
Description:
Indicates if a vector named vecName exists in interp.
Results:
Returns 1 if a vector vecName exists and 0 otherwise.

If your application needs to be notified when a vector changes, it can allocate a unique client identifier for itself. Using this identifier, you can then register a call-back to be made whenever the vector is updated or destroyed. By default, the call-backs are made at the next idle point. This can be changed to occur at the time the vector is modified. An application can allocate more than one identifier for any vector. When the client application is done with the vector, it should free the identifier.

The call-back routine must of the following type.


typedef void (Blt_VectorChangedProc) (Tcl_Interp *interp,
ClientData clientData, Blt_VectorNotify notify);

ClientData is passed to this routine whenever it is called. You can use this to pass information to the call-back. The notify 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
} Blt_VectorNotify;

Blt_AllocVectorId

Synopsis:

Blt_VectorId Blt_AllocVectorId (interp, vecName)
Tcl_Interp *interp;
char *vecName;
Description:
Allocates an client identifier for with the vector vecName. 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 vecName is not the name of a vector, then NULL is returned and interp->result will contain an error message.

Blt_GetVectorById

Synopsis:

int Blt_GetVector (interp, clientId, vecPtrPtr)
Tcl_Interp *interp;
Blt_VectorId clientId;
Blt_Vector **vecPtrPtr;
Description:
Retrieves the vector used by clientId. ClientId is a valid vector client identifier allocated by Blt_AllocVectorId. VecPtrPtr will point be set to the address of the vector.
Results:
Returns TCL_OK if the vector is successfully retrieved.

Blt_SetVectorChangedProc

Synopsis:

void Blt_SetVectorChangedProc (clientId, proc, clientData);
Blt_VectorId clientId;
Blt_VectorChangedProc *proc;
ClientData *clientData;
Description:
Specifies a call-back routine to be called whenever the vector associated with clientId is updated or deleted. Proc is a pointer to call-back routine and must be of the type Blt_VectorChangedProc. ClientData is a one-word value to be passed to the routine when it is invoked. If proc is NULL, then the client is not notified.
Results:
The designated call-back procedure will be invoked when the vector is updated or destroyed.

Blt_FreeVectorId

Synopsis:

void Blt_FreeVectorId (clientId);
Blt_VectorId clientId;
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.

Blt_NameOfVectorId

Synopsis:

char *Blt_NameOfVectorId (clientId);
Blt_VectorId clientId;
Description:
Retrieves the name of the vector associated with the client identifier clientId.
Results:
Returns the name of the vector associated with clientId. If clientId is not an identifier or the vector has been destroyed, NULL is returned.

Blt_InstallIndexProc

Synopsis:

void Blt_InstallIndexProc (indexName, procPtr)
char *indexName;
Blt_VectorIndexProc *procPtr;
Description:
Registers a function to be called to retrieved the index indexName from the vector's array variable.

typedef double Blt_VectorIndexProc(Vector *vecPtr);

The function will be passed a pointer to the vector. The function must return a double representing the value at the index.

Results:
The new index is installed into the vector.

C API Example

The following example opens a file of binary data and stores it in an array of doubles. The array size is computed from the size of the file. If the vector "data" exists, calling Blt_VectorExists, Blt_GetVector is called to get the pointer to the vector. Otherwise the routine Blt_CreateVector is called to create a new vector and returns a pointer to it. Just like the Tcl interface, both a new Tcl command and array variable are created when a new vector is created. It doesn't make any difference what the initial size of the vector is since it will be reset shortly. The vector is updated when lt_ResetVector 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 = (double *)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;
}

Incompatibilities

In previous versions, if the array variable isn't global (i.e. local to a Tcl procedure), the vector is automatically destroyed when the procedure returns.
proc doit {} {
# Temporary vector x
vector x(10)
set x(9) 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.

Keywords

vector, graph, Blt_Vector

Table of Contents