HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
GA_AIFSharedStringTuple.h
Go to the documentation of this file.
1 /*
2  * PROPRIETARY INFORMATION. This software is proprietary to
3  * Side Effects Software Inc., and is not to be reproduced,
4  * transmitted, or disclosed in any way without written permission.
5  *
6  * NAME: GA_AIFSharedStringTuple.h ( GA Library, C++)
7  *
8  * COMMENTS: Attribute Interface class for string index table methods
9  */
10 
11 #ifndef __GA_AIFSharedStringTuple__
12 #define __GA_AIFSharedStringTuple__
13 
14 #include "GA_API.h"
15 
16 #include "GA_AIFStringTuple.h"
17 #include "GA_BlobContainer.h"
18 #include "GA_Types.h"
19 
20 #include <UT/UT_Array.h>
21 #include <UT/UT_VectorTypes.h>
22 
23 #include <stddef.h>
24 
25 
26 class GA_Attribute;
27 class GA_Range;
29 
30 
31 /// Index type
32 /// WARNING: We assume that GA_StringIndexType and GA_BlobIndexType
33 /// are binare compatible, so do not change this!
35 #define GA_INVALID_STRING_INDEX GA_StringIndexType(-1)
36 
38 {
39 public:
41  : myCapacity(0)
42  , myEntries(0)
43  {
44  }
46 
47  GA_Size getEntries() const { return myEntries; }
48  GA_Size getCapacity() const { return myCapacity; }
49 
50  void setEntries(GA_Size n) { myEntries = n; }
51  void setCapacity(GA_Size n) { myCapacity = n; }
52 private:
53  GA_Size myEntries, myCapacity;
54 };
55 
56 /// @brief A specialization of GA_AIFStringTuple to access "shared strings"
57 ///
58 /// This class provides the interface to access string table data. Each
59 /// attribute type may provide this interface if it makes sense.
61 {
62 public:
64  virtual ~GA_AIFSharedStringTuple();
65 
66  /// Query information about the string storage.
67  virtual bool getStatistics(const GA_Attribute *attrib,
68  GA_StringTableStatistics &stats) const = 0;
69 
70  /// Compact the string storage
71  virtual bool compactStorage(GA_Attribute *attrib) const = 0;
72 
73  /// Extract data from the string table. This will extract all the unique
74  /// strings which are referenced by the attribute.
75  /// The string handles are guaranteed to be in ascending order, but
76  /// may or may not be contiguous.
77  virtual bool extractStrings(const GA_Attribute *attrib,
79  UT_IntArray &handles) const = 0;
80  /// Stop after reaching a maximum
81  virtual bool extractStrings(const GA_Attribute *attrib,
82  UT_StringArray &strings,
83  UT_IntArray &handles,
84  exint maxstrings) const = 0;
85 
86  /// Extract all of the unique string handles of the attribute.
87  /// The string handles are guaranteed to be in ascending order, but
88  /// may or may not be contiguous.
89  virtual bool extractHandles(const GA_Attribute *attrib,
90  UT_IntArray &handles) const = 0;
91 
92 public:
93  // --------------------------------------------------------------
94  // Interface to deal with string handles.
95  // --------------------------------------------------------------
96 
97  /// Return the number of entries in the shared string table
98  GA_Size getTableEntries(const GA_Attribute *attrib) const
99  {
101  if (attrib && getStatistics(attrib, stats))
102  return stats.getCapacity();
103  return 0;
104  }
105 
106  /// It's possible that there are invalid handle indexes mixed with the
107  /// valid handles. When iterating over all the handles, you can call @c
108  /// validateTableHandle() which will ensure that there's a string
109  /// associated with the given handle.
110  virtual GA_StringIndexType validateTableHandle(const GA_Attribute *attrib,
111  GA_StringIndexType index) const = 0;
112 
113  /// Get a string from the string table (without going through an attribute)
114  virtual const char *getTableString(const GA_Attribute *attrib,
115  GA_StringIndexType handle) const = 0;
116 
117  /// Get the handle (index) corresponding to the given string, returning -1
118  /// if none.
119  virtual GA_StringIndexType getTableHandle(const GA_Attribute *attrib,
120  const char *string) const = 0;
121 
122  /// GA_StringIndexType indices may not be contiguous, this method allows
123  /// you to get a string given an ordered index. Strings will be defined
124  /// for all contiguous strings. This may be an expensive operation, it's
125  /// better to access strings by their index if possible.
126  ///
127  /// This method will return a NULL pointer past the end of the string table
128  virtual const char *getTableOrderedString(const GA_Attribute *a,
129  exint index) const = 0;
130 
131 
132  /// Replace a string in the shared string table with a new value. Warning,
133  /// it's possible that the table will "collapse" after the replacement.
134  /// For example: @code
135  /// table := [ "foo", "bar" ]
136  /// table.replaceString(1, "foo") # Replace "bar" with "foo"
137  /// table := [ "foo" ]
138  /// @endcode
139  /// In the above example, all elements which originally referenced "bar"
140  /// will now reference "foo". This means that trying to swap two values
141  /// will not work as expected.
142  virtual bool replaceTableString(GA_Attribute *attrib,
143  GA_StringIndexType handle,
144  const char *string) const = 0;
145 
146  /// Class to iterate over all the strings in the shared string table
148  {
149  public:
151  : myAIF(NULL)
152  , myAttrib(NULL)
153  , myString(NULL)
154  , myCount(0)
155  , myIndex(0)
156  {
157  }
160  {
161  myAIF = src.myAIF;
162  myAttrib = src.myAttrib;
163  myString = src.myString;
164  myCount = src.myCount;
165  myIndex = src.myIndex;
166  return *this;
167  }
168  bool operator==(const iterator &src)
169  {
170  if (!src.myAIF)
171  return atEnd();
172  if (!myAIF)
173  return src.atEnd();
174  return myAIF == src.myAIF &&
175  myAttrib == src.myAttrib &&
176  myCount == src.myCount &&
177  myIndex == src.myIndex;
178  }
179  iterator &operator++() { advance(); return *this; }
180  iterator &operator++(int) { advance(); return *this; }
181 
182  void rewind()
183  {
184  myIndex = 0;
185  setupString();
186  }
187  bool atEnd() const { return myIndex >= myCount; }
188  void advance()
189  {
190  myIndex++;
191  setupString();
192  }
193  GA_Size getCount() const { return myCount; }
194  GA_Size getIndex() const { return myIndex; }
196  { return GA_StringIndexType(myIndex); }
197  const char *getString() const { return myString; }
198  private:
199  void setupString()
200  {
201  while (myIndex < myCount)
202  {
203  myString = myAIF->getTableString(myAttrib,
204  GA_StringIndexType(myIndex));
205  if (myString)
206  break;
207  myIndex++;
208  }
209  }
210  iterator(const GA_AIFSharedStringTuple *aif,
211  const GA_Attribute *a)
212  : myAIF(aif)
213  , myAttrib(a)
214  , myString(NULL)
215  , myIndex(0)
216  , myCount(aif ? aif->getTableEntries(a) : 0)
217  {
218  setupString();
219  }
220 
221  const GA_AIFSharedStringTuple *myAIF;
222  const GA_Attribute *myAttrib;
223  const char *myString;
224  GA_Size myCount;
225  GA_Size myIndex;
227  };
228 
229  iterator begin(const GA_Attribute *a) const
230  { return iterator(this, a); }
231  iterator end() const
232  { return iterator(); }
233 
234 protected:
235  /// Add (or increment) reference to a string
237  const char *string) const = 0;
238  /// Decrement reference to a handle
239  virtual void delHandleReference(GA_Attribute *attribute,
240  GA_StringIndexType handle) const = 0;
241 
242 public:
243  // --------------------------------------------------------------
244  // Tuple Interface
245  // --------------------------------------------------------------
246 
247  /// Query the tuple size
248  virtual int getTupleSize(const GA_Attribute *attrib) const = 0;
249 
250  /// Set the tuple size
251  virtual bool setTupleSize(GA_Attribute *attrib, int size) const = 0;
252 
253  /// Get a single string from the array for a single tuple of an element.
254  virtual const char *getString(const GA_Attribute *attrib, GA_Offset ai,
255  int tuple_index=0) const;
256 
257  /// Get the handle from the array for a single tuple of an element
258  virtual GA_StringIndexType getHandle(const GA_Attribute *attrib,
259  GA_Offset ai,
260  int tuple_index=0) const = 0;
261 
262  /// Get the full tuple of indices for a single element
263  virtual bool getHandles(const GA_Attribute *attrib, GA_Offset ai,
264  GA_StringIndexType *handles,
265  int count, int start=0) const;
266 
267  /// Set a single component for a single element.
268  virtual bool setString(GA_Attribute *attrib, GA_Offset ai,
269  const char *string, int tuple_index) const;
270  /// Set a single component for a range of elements.
271  virtual bool setString(GA_Attribute *attrib, const GA_Range &ai,
272  const char *string, int tuple_index) const;
273  /// Set a single component for a single element.
274  virtual bool setHandle(GA_Attribute *attrib, GA_Offset ai,
275  GA_StringIndexType handle,
276  int tuple_index) const = 0;
277  /// Set a single component for a range of elements.
278  virtual bool setHandle(GA_Attribute *attrib, const GA_Range &ai,
279  GA_StringIndexType handle,
280  int tuple_index) const;
281 
282  /// Set multiple components for a single element
283  virtual bool setHandles(GA_Attribute *attrib, GA_Offset ai,
284  const GA_StringIndexType *handles,
285  int count, int start=0) const;
286  /// Set multiple components for a range of elements
287  virtual bool setHandles(GA_Attribute *attrib, const GA_Range &ai,
288  const GA_StringIndexType *handles,
289  int count, int start=0) const;
290 
291 public:
292  // --------------------------------------------------------------
293  // Interface to deal with a detail attribute as a list of strings
294  //
295  // By default interface uses the simple tuple interface defined above.
296  // --------------------------------------------------------------
297 
298  /// @{
299  /// Array API, select functions can be more efficiently implemented using
300  /// shared strings.
301  /// Please see GA_AIFStringTuple for remainder of interface
302  virtual int arrayGetLength(const GA_Attribute *attrib,
303  GA_Offset element_index=GA_Offset(0)) const;
304  virtual int arrayFindString(const GA_Attribute *attrib,
305  const char *string,
306  GA_Offset element_index=GA_Offset(0)) const;
307  virtual bool arrayDestroyString(GA_Attribute *attrib,
308  int string_index,
309  GA_Offset element_index=GA_Offset(0)) const;
310  /// @}
311 
312 public:
313  /// @brief Temporary container to hold references to multiple strings
314  ///
315  /// In some cases, it's more expedient to add multiple strings to the
316  /// attribute, and then assign the string values after the fact. This
317  /// class is similar to the GA_AIFBlob::BlobBuffer class, but is
318  /// specialized for shared string attributes.
320  {
321  public:
322  StringBuffer(GA_Attribute *attribute = NULL,
323  const GA_AIFSharedStringTuple *aif=NULL);
325  : myAttribute(NULL)
326  , myAIFSharedStringTuple(NULL)
327  {
328  *this = src;
329  }
331  {
332  clear();
333  }
334 
335  StringBuffer &operator=(const StringBuffer &src);
336 
337  /// Return number of strings referenced in the string buffer
338  GA_Size entries() const { return myHandleList.entries(); }
339 
340  /// Add a string to the attribute. Returns the handle of the string in
341  /// the attribute (not the string's index in the buffer).
342  GA_StringIndexType append(const char *string);
343 
344  /// Return the string index from the buffer. The index refers to the
345  /// buffer index (not the string handle).
346  GA_StringIndexType getStringIndex(GA_Size i) const;
347  /// Return a string handle from the buffer. The index refers to the
348  /// buffer index (not the string handle).
349  const char *getString(GA_Size i) const;
350 
351  /// Clear references to all strings contained in the buffer.
352  void clear();
353  private:
354  UT_Array<GA_StringIndexType> myHandleList;
355  const GA_AIFSharedStringTuple *myAIFSharedStringTuple;
356  GA_Attribute *myAttribute;
357  };
358 
359  /// @{
360  /// Method to add multiple strings in a batch process. The strings will be
361  /// temporarily added to the attribute for as long as the StringBuffer
362  /// exists. When the StringBuffer is deleted, the strings will be deleted
363  /// from the attribute unless referenced by elements in the attribute
364  /// array.
365  ///
366  /// Information about the strings (i.e. the handles) can be retriefed from
367  /// the StringBuffer. For example: @code
368  /// UT_StringArray s(strings);
369  /// GA_AIFSharedStringTuple::StringBuffer handles;
370  /// handles = a->getAIFSharedStringTuple()->addStrings(s);
371  /// for (GA_Size i = 0; i < handles.entries(); ++i)
372  /// cerr << s(i) << " handle=" << handles.getStringIndex(i) << endl;
373  /// @endcode
374  StringBuffer addStrings(GA_Attribute *attribute,
375  const UT_StringArray &strings) const;
376  StringBuffer addStrings(GA_Attribute *attribute,
377  const UT_Array<const char *> &strings) const;
378  /// @}
379  friend class StringBuffer; // Allow the string buffer to add refs
380 };
381 
382 #endif
Definition of a geometry attribute.
Definition: GA_Attribute.h:189
Temporary container to hold references to multiple strings.
virtual void delHandleReference(GA_Attribute *attribute, GA_StringIndexType handle) const =0
Decrement reference to a handle.
GA_Size entries() const
Return number of strings referenced in the string buffer.
GLuint start
Definition: glcorearb.h:474
GLboolean GLboolean GLboolean GLboolean a
Definition: glcorearb.h:1221
#define GA_API
Definition: GA_API.h:12
GA_Size getTableEntries(const GA_Attribute *attrib) const
Return the number of entries in the shared string table.
png_uint_32 i
Definition: png.h:2877
exint GA_Size
Defines the bit width for index and offset types in GA.
Definition: GA_Types.h:211
GLsizeiptr size
Definition: glcorearb.h:663
virtual GA_StringIndexType addStringReference(GA_Attribute *attribute, const char *string) const =0
Add (or increment) reference to a string.
A range of elements in an index-map.
Definition: GA_Range.h:42
virtual bool setHandles(GA_Attribute *attrib, GA_Offset ai, const GA_StringIndexType *handles, int count, int start=0) const
Set multiple components for a single element.
GA_Size GA_Offset
Definition: GA_Types.h:617
GLdouble n
Definition: glcorearb.h:2007
virtual int arrayGetLength(const GA_Attribute *attrib, GA_Offset element_index=GA_Offset(0)) const
UT_IndexedHashMapItemId GA_BlobIndex
int64 exint
Definition: SYS_Types.h:115
iterator & operator=(const iterator &src)
virtual bool getHandles(const GA_Attribute *attrib, GA_Offset ai, GA_StringIndexType *handles, int count, int start=0) const
Get the full tuple of indices for a single element.
GLsizei const GLchar *const * strings
Definition: glcorearb.h:1932
GLint GLsizei count
Definition: glcorearb.h:404
virtual bool setString(GA_Attribute *attrib, GA_Offset ai, const char *string, int tuple_index) const
Set a single component for a single element.
GA_StringIndexType getHandle() const
virtual bool setTupleSize(GA_Attribute *attrib, int size) const =0
Set the tuple size.
Class to iterate over all the strings in the shared string table.
GLuint index
Definition: glcorearb.h:785
virtual int getTupleSize(const GA_Attribute *attrib) const =0
Query the tuple size.
A specialization of GA_AIFStringTuple to access "shared strings".
GA_BlobIndex GA_StringIndexType
iterator begin(const GA_Attribute *a) const
virtual bool arrayDestroyString(GA_Attribute *attrib, int string_index, GA_Offset element_index=GA_Offset(0)) const
virtual const char * getString(const GA_Attribute *attrib, GA_Offset ai, int tuple_index=0) const
Get a single string from the array for a single tuple of an element.
virtual int arrayFindString(const GA_Attribute *attrib, const char *string, GA_Offset element_index=GA_Offset(0)) const
virtual bool setHandle(GA_Attribute *attrib, GA_Offset ai, GA_StringIndexType handle, int tuple_index) const =0
Set a single component for a single element.
virtual GA_StringIndexType getHandle(const GA_Attribute *attrib, GA_Offset ai, int tuple_index=0) const =0
Get the handle from the array for a single tuple of an element.
Generic Attribute Interface class to work with string indices directly, rather than string values...
GLenum src
Definition: glcorearb.h:1792