util/src/TclTk/blt2.5/generic/bltTuple.h

   1
   2 /*
   3  * bltTuple.h --
   4  *
   5  * Copyright 1998-1999 Lucent Technologies, Inc.
   6  *
   7  * Permission to use, copy, modify, and distribute this software and
   8  * its documentation for any purpose and without fee is hereby
   9  * granted, provided that the above copyright notice appear in all
  10  * copies and that both that the copyright notice and warranty
  11  * disclaimer appear in supporting documentation, and that the names
  12  * of Lucent Technologies or any of their entities not be used in
  13  * advertising or publicity pertaining to distribution of the software
  14  * without specific, written prior permission.
  15  *
  16  * Lucent Technologies disclaims all warranties with regard to this
  17  * software, including all implied warranties of merchantability and
  18  * fitness.  In no event shall Lucent Technologies be liable for any
  19  * special, indirect or consequential damages or any damages
  20  * whatsoever resulting from loss of use, data or profits, whether in
  21  * an action of contract, negligence or other tortuous action, arising
  22  * out of or in connection with the use or performance of this
  23  * software.
  24  *
  25  *      The tuple data object was created by George A. Howlett.
  26  */
  27
  28 #ifndef _BLT_TUPLE_H
  29 #define _BLT_TUPLE_H
  30
  31 #include <bltChain.h>
  32 #include <bltHash.h>
  33 #include <bltPool.h>
  34
  35 /*
  36  *  array or row pointers
  37  *   _
  38  *  |_---> [row index
  39  *  |_     [#columns             array of Tcl_Objs
  40  *  |_     [tuple pointer ---> [ . . . . . ]
  41  *  |_
  42  *  |_
  43  *  |_
  44  *  |_
  45  *  |_
  46  *  |_
  47  *  |_
  48  *  |_
  49  *  |_
  50  *  |_
  51  *  |_
  52  *  |_
  53  *  |_
  54  *  |_
  55  *  |_
  56  *  |_
  57  *  |_
  58  *  |_
  59  *
  60  */
  61 typedef struct Blt_TupleRowStruct *Blt_Tuple;
  62 typedef struct Blt_TupleTraceStruct *Blt_TupleTrace;
  63 typedef struct Blt_TupleNotifierStruct *Blt_TupleNotifier;
  64 typedef struct Blt_TupleClientStruct *Blt_TupleTable;
  65
  66 typedef struct Blt_TupleColumnStruct Blt_TupleColumn;
  67 typedef struct Blt_TupleRowStruct Blt_TupleRow;
  68 typedef struct Blt_TupleTagTableStruct Blt_TupleTagTable;
  69
  70 #define TUPLE_NOTIFY_CREATE_COLUMN      (1<<0)
  71 #define TUPLE_NOTIFY_CREATE_ROW         (1<<1)
  72 #define TUPLE_NOTIFY_CREATE \
  73         (TUPLE_NOTIFY_CREATE_COLUMN|TUPLE_NOTIFY_CREATE_ROW)
  74 #define TUPLE_NOTIFY_DELETE_ROW         (1<<2)
  75 #define TUPLE_NOTIFY_DELETE_COLUMN      (1<<3)
  76 #define TUPLE_NOTIFY_DELETE \
  77         (TUPLE_NOTIFY_DELETE_COLUMN|TUPLE_NOTIFY_DELETE_ROW)
  78 #define TUPLE_NOTIFY_MOVE               (1<<4)
  79 #define TUPLE_NOTIFY_SORT               (1<<5)
  80 #define TUPLE_NOTIFY_RELABEL            (1<<6)
  81 #define TUPLE_NOTIFY_ALL        \
  82          (TUPLE_NOTIFY_CREATE | TUPLE_NOTIFY_DELETE | TUPLE_NOTIFY_MOVE | \
  83           TUPLE_NOTIFY_SORT   | TUPLE_NOTIFY_RELABEL)
  84 #define TUPLE_NOTIFY_MASK               (TUPLE_NOTIFY_ALL)
  85
  86 #define TUPLE_NOTIFY_WHENIDLE    (1<<8)
  87 #define TUPLE_NOTIFY_FOREIGN_ONLY (1<<9)
  88 #define TUPLE_NOTIFY_ACTIVE      (1<<10)
  89
  90 typedef struct {
  91     int type;                   /* Indicates type of event received. */
  92     int row;                    /* Index of tuple receiving the event. */
  93     Tcl_Interp *interp;         /* Interpreter to report to */
  94     Blt_TupleTable table;       /* Tuple object client that received
  95                                  * the event. */
  96 } Blt_TupleNotifyEvent;
  97
  98 typedef int (Blt_TupleNotifyEventProc)(ClientData clientData,
  99         Blt_TupleNotifyEvent *eventPtr);
 100
 101 struct Blt_TupleNotifierStruct {
 102     Blt_TupleTable table;
 103     Blt_ChainLink *linkPtr;
 104     Blt_TupleNotifyEvent event;
 105     Blt_TupleNotifyEventProc *proc;
 106     ClientData clientData;
 107     Tcl_Interp *interp;
 108     char *key;
 109     int notifyPending;
 110     unsigned int mask;
 111 };
 112
 113
 114 EXTERN Blt_TupleNotifier Blt_TupleCreateNotifier(Blt_TupleTable table,
 115         unsigned int mask, Blt_TupleNotifyEventProc *proc,
 116         ClientData clientData);
 117
 118 EXTERN void Blt_TupleDeleteNotifier(Blt_TupleNotifier notifier);
 119
 120 typedef struct {
 121     char *tagName;
 122     Blt_HashEntry *hashPtr;
 123     Blt_HashTable rowTable;     /* Hash table of row pointers.  This
 124                                  * represents all the rows tagged by
 125                                  * this tag. */
 126 } Blt_TupleTagEntry;
 127
 128 typedef struct {
 129     Blt_TupleTable table;
 130     int tagType;
 131     unsigned int row, nRows;
 132     Blt_HashSearch cursor;
 133     Blt_HashTable *rowTablePtr;
 134 } Blt_TupleTagSearch;
 135
 136 EXTERN Blt_Tuple Blt_TupleFirstTagged(Tcl_Interp *interp, Blt_TupleTable table,
 137         Tcl_Obj *objPtr, Blt_TupleTagSearch *cursorPtr);
 138 EXTERN Blt_Tuple Blt_TupleNextTagged(Blt_TupleTagSearch *cursorPtr);
 139
 140 EXTERN void Blt_TupleClearTags(Blt_TupleTable table, Blt_Tuple tuple);
 141 EXTERN void Blt_TupleRemoveTag(Blt_TupleTable table, Blt_Tuple tuple,
 142         CONST char *tagName);
 143 EXTERN int Blt_TupleHasTag(Blt_TupleTable table, Blt_Tuple tuple,
 144         CONST char *tagName);
 145 EXTERN void Blt_TupleAddTag(Blt_TupleTable table, Blt_Tuple tuple,
 146         CONST char *tagName);
 147 EXTERN void Blt_TupleForgetTag(Blt_TupleTable table, CONST char *tagName);
 148 EXTERN Blt_HashTable *Blt_TupleTagHashTable(Blt_TupleTable table,
 149         CONST char *tagName);
 150 EXTERN int Blt_TupleTagTableIsShared(Blt_TupleTable table);
 151
 152 #define TUPLE_TRACE_UNSET       (1<<3)
 153 #define TUPLE_TRACE_WRITE       (1<<4)
 154 #define TUPLE_TRACE_READ        (1<<5)
 155 #define TUPLE_TRACE_CREATE      (1<<6)
 156 #define TUPLE_TRACE_ALL         \
 157         (TUPLE_TRACE_UNSET | TUPLE_TRACE_WRITE | TUPLE_TRACE_READ  | \
 158         TUPLE_TRACE_CREATE)
 159 #define TUPLE_TRACE_MASK        (TUPLE_TRACE_ALL)
 160
 161 #define TUPLE_TRACE_FOREIGN_ONLY (1<<8)
 162 #define TUPLE_TRACE_ACTIVE      (1<<9)
 163
 164 typedef int (Blt_TupleTraceProc)(ClientData clientData, Tcl_Interp *interp,
 165         unsigned int row, unsigned int column, unsigned int flags);
 166
 167 struct Blt_TupleTraceStruct {
 168     Tcl_Interp *interp;
 169     Blt_ChainLink *linkPtr;
 170     Blt_TupleTable table;
 171     Blt_Tuple tuple;
 172     CONST char **keys;
 173     char *withTag;
 174     unsigned int mask;
 175     Blt_TupleTraceProc *proc;
 176     ClientData clientData;
 177 };
 178
 179 EXTERN Blt_TupleTrace Blt_TupleCreateTrace(Blt_TupleTable table,
 180         Blt_Tuple tuple, CONST char *tagName, CONST char *keyList,
 181         unsigned int mask, Blt_TupleTraceProc *proc, ClientData clientData);
 182
 183 EXTERN void Blt_TupleDeleteTrace(Blt_TupleTrace trace);
 184
 185 EXTERN int Blt_TupleGetValueByIndex(Tcl_Interp *interp, Blt_TupleTable table,
 186         unsigned int row, unsigned int column, Tcl_Obj **objPtrPtr);
 187 EXTERN int Blt_TupleSetValueByIndex(Tcl_Interp *interp, Blt_TupleTable table,
 188         unsigned int row, unsigned int column, Tcl_Obj *objPtr);
 189 EXTERN int Blt_TupleUnsetValueByIndex(Tcl_Interp *interp, Blt_TupleTable table,
 190         unsigned int row, unsigned int column);
 191 EXTERN int Blt_TupleGetValue(Tcl_Interp *interp, Blt_TupleTable table,
 192         Blt_Tuple tuple, CONST char *key, Tcl_Obj **objPtrPtr);
 193 EXTERN int Blt_TupleSetValue(Tcl_Interp *interp, Blt_TupleTable table,
 194         Blt_Tuple tuple, CONST char *key, Tcl_Obj *objPtr);
 195 EXTERN int Blt_TupleUnsetValue(Tcl_Interp *interp, Blt_TupleTable table,
 196         Blt_Tuple tuple, CONST char *key);
 197
 198 EXTERN int Blt_TupleGetArrayValue(Tcl_Interp *interp, Blt_TupleTable table,
 199         Blt_Tuple tuple, CONST char *key, CONST char *elemName,
 200         Tcl_Obj **objPtrPtr);
 201 EXTERN int Blt_TupleSetArrayValue(Tcl_Interp *interp, Blt_TupleTable table,
 202         Blt_Tuple tuple, CONST char *key, CONST char *elemName,
 203         Tcl_Obj *objPtr);
 204 EXTERN int Blt_TupleUnsetArrayValue(Tcl_Interp *interp, Blt_TupleTable table,
 205         Blt_Tuple tuple, CONST char *key, CONST char *elemName);
 206
 207 EXTERN unsigned int Blt_TupleAddColumn(Blt_TupleTable table, CONST char *key,
 208         int *isNewPtr);
 209 EXTERN unsigned int Blt_TupleRowIndex(Blt_Tuple tuple);
 210 EXTERN CONST char *Blt_TupleGetColumnKey(Blt_TupleTable table, int column);
 211 EXTERN Blt_HashEntry *Blt_TupleFirstTag(Blt_TupleTable table,
 212         Blt_HashSearch *cursorPtr);
 213 EXTERN Blt_Tuple Blt_TupleGetTupleByIndex(Blt_TupleTable table,
 214         unsigned int row);
 215 EXTERN int Blt_TupleExtendRows(Blt_TupleTable table, unsigned int extra);
 216 EXTERN Blt_Tuple Blt_TupleNextTuple(Blt_TupleTable table, Blt_Tuple tuple);
 217 EXTERN void Blt_TupleStartDeleteRows(Blt_TupleTable table);
 218 EXTERN void Blt_TupleDeleteTuple(Blt_TupleTable table, Blt_Tuple tuple);
 219 EXTERN void Blt_TupleEndDeleteRows(Blt_TupleTable table);
 220
 221 EXTERN int Blt_TupleTableExists(Tcl_Interp *interp, CONST char *objName);
 222 EXTERN int Blt_TupleCreateTable(Tcl_Interp *interp, CONST char *name,
 223         Blt_TupleTable *tablePtr);
 224 EXTERN int Blt_TupleGetTable(Tcl_Interp *interp, CONST char *name,
 225         Blt_TupleTable *tablePtr);
 226 EXTERN void Blt_TupleReleaseTable(Blt_TupleTable table);
 227
 228 EXTERN CONST char *Blt_TupleTableName(Blt_TupleTable table);
 229 EXTERN unsigned int Blt_TupleTableLength(Blt_TupleTable table);
 230 EXTERN unsigned int Blt_TupleTableWidth(Blt_TupleTable table);
 231
 232 #endif /* BLT_TUPLE_H */