PTLib  Version 2.10.11
array.h
Go to the documentation of this file.
1 /*
2  * array.h
3  *
4  * Linear Array Container classes.
5  *
6  * Portable Tools Library
7  *
8  * Copyright (c) 1993-1998 Equivalence Pty. Ltd.
9  *
10  * The contents of this file are subject to the Mozilla Public License
11  * Version 1.0 (the "License"); you may not use this file except in
12  * compliance with the License. You may obtain a copy of the License at
13  * http://www.mozilla.org/MPL/
14  *
15  * Software distributed under the License is distributed on an "AS IS"
16  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
17  * the License for the specific language governing rights and limitations
18  * under the License.
19  *
20  * The Original Code is Portable Windows Library.
21  *
22  * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
23  *
24  * Portions are Copyright (C) 1993 Free Software Foundation, Inc.
25  * All Rights Reserved.
26  *
27  * Contributor(s): ______________________________________.
28  *
29  * $Revision: 25387 $
30  * $Author: rjongbloed $
31  * $Date: 2011-03-22 22:51:09 -0500 (Tue, 22 Mar 2011) $
32  */
33 
34 #ifndef PTLIB_ARRAY_H
35 #define PTLIB_ARRAY_H
36 
37 #ifdef P_USE_PRAGMA
38 #pragma interface
39 #endif
40 
41 #include <ptlib/contain.h>
42 
44 // The abstract array class
45 
67 class PAbstractArray : public PContainer
68 {
69  PCONTAINERINFO(PAbstractArray, PContainer);
70  public:
83  PINDEX elementSizeInBytes,
84  PINDEX initialSize = 0
86  );
87 
106  PINDEX elementSizeInBytes,
107  const void *buffer,
109  PINDEX bufferSizeInElements,
110  PBoolean dynamicAllocation
111  );
113 
122  virtual void PrintOn(
123  ostream &strm // Stream to print the object into.
124  ) const;
125 
132  virtual void ReadFrom(
133  istream &strm // Stream to read the objects contents from.
134  );
135 
155  virtual Comparison Compare(
156  const PObject & obj
157  ) const;
159 
170  virtual PBoolean SetSize(
171  PINDEX newSize
172  );
174 
185  void Attach(
186  const void *buffer,
187  PINDEX bufferSize
188  );
189 
203  void * GetPointer(
204  PINDEX minSize = 1
205  );
206 
220  const PAbstractArray & array
221  );
223 
224  protected:
225  PBoolean InternalSetSize(PINDEX newSize, PBoolean force);
226 
227  virtual void PrintElementOn(
228  ostream & stream,
229  PINDEX index
230  ) const;
231  virtual void ReadElementFrom(
232  istream & stream,
233  PINDEX index
234  );
235 
238  PINDEX elementSizeInBytes
239  );
240 
242  PINDEX elementSize;
243 
245  char * theArray;
246 
249 
250  friend class PArrayObjects;
251 };
252 
253 
255 // An array of some base type
256 
274 template <class T> class PBaseArray : public PAbstractArray
275 {
276  PCLASSINFO(PBaseArray, PAbstractArray);
277  public:
286  PINDEX initialSize = 0
287  ) : PAbstractArray(sizeof(T), initialSize) { }
288 
292  T const * buffer,
293  PINDEX length,
294  PBoolean dynamic = true
295  ) : PAbstractArray(sizeof(T), buffer, length, dynamic) { }
297 
302  virtual PObject * Clone() const
303  {
304  return PNEW PBaseArray<T>(*this, GetSize());
305  }
307 
317  PINDEX index,
318  T val
319  ) {
320  return SetMinSize(index+1) && val==(((T *)theArray)[index] = val);
321  }
322 
329  T GetAt(
330  PINDEX index
331  ) const {
332  PASSERTINDEX(index);
333  return index < GetSize() ? ((T *)theArray)[index] : (T)0;
334  }
335 
344  void Attach(
345  const T * buffer,
346  PINDEX bufferSize
347  ) {
348  PAbstractArray::Attach(buffer, bufferSize);
349  }
350 
365  PINDEX minSize = 0
366  ) {
367  return (T *)PAbstractArray::GetPointer(minSize);
368  }
370 
383  PINDEX index
384  ) const {
385  return GetAt(index);
386  }
387 
399  PINDEX index
400  ) {
401  PASSERTINDEX(index);
402  PAssert(SetMinSize(index+1), POutOfMemory);
403  return ((T *)theArray)[index];
404  }
405 
419  operator T const *() const {
420  return (T const *)theArray;
421  }
422 
435  const PBaseArray & array
436  ) {
437  return PAbstractArray::Concatenate(array);
438  }
440 
441  protected:
442  virtual void PrintElementOn(
443  ostream & stream,
444  PINDEX index
445  ) const {
446  stream << GetAt(index);
447  }
448 
450 };
451 
460 #define PBASEARRAY(cls, T) typedef PBaseArray<T> cls
461 
474 #define PDECLARE_BASEARRAY(cls, T) \
475  PDECLARE_CLASS(cls, PBaseArray<T>) \
476  cls(PINDEX initialSize = 0) \
477  : PBaseArray<T>(initialSize) { } \
478  cls(PContainerReference & reference) \
479  : PBaseArray<T>(reference) { } \
480  cls(T const * buffer, PINDEX length, PBoolean dynamic = true) \
481  : PBaseArray<T>(buffer, length, dynamic) { } \
482  virtual PObject * Clone() const \
483  { return PNEW cls(*this, GetSize()); } \
484 
485 
502 template <class T> class PScalarArray : public PBaseArray<T>
503 {
504  public:
513  PINDEX initialSize = 0
514  ) : PBaseArray<T>(initialSize) { }
515 
519  T const * buffer,
520  PINDEX length,
521  PBoolean dynamic = true
522  ) : PBaseArray<T>(buffer, length, dynamic) { }
524 
525  protected:
526  virtual void ReadElementFrom(
527  istream & stream,
528  PINDEX index
529  ) {
530  T t;
531  stream >> t;
532  if (!stream.fail())
533  this->SetAt(index, t);
534  }
535 };
536 
537 
546 #define PSCALAR_ARRAY(cls, T) typedef PScalarArray<T> cls
547 
548 
550 #ifdef DOC_PLUS_PLUS
551 class PCharArray : public PBaseArray {
552  public:
558  PCharArray(
559  PINDEX initialSize = 0
560  );
561 
564  PCharArray(
565  char const * buffer,
566  PINDEX length,
567  PBoolean dynamic = true
568  );
570 #else
572 #endif
573  public:
576  virtual void PrintOn(
578  ostream & strm
579  ) const;
581  virtual void ReadFrom(
582  istream &strm // Stream to read the objects contents from.
583  );
585 };
586 
588 #ifdef DOC_PLUS_PLUS
589 class PShortArray : public PBaseArray {
590  public:
596  PShortArray(
597  PINDEX initialSize = 0
598  );
599 
602  PShortArray(
603  short const * buffer,
604  PINDEX length,
605  PBoolean dynamic = true
606  );
608 };
609 #else
610 PSCALAR_ARRAY(PShortArray, short);
611 #endif
612 
613 
615 #ifdef DOC_PLUS_PLUS
616 class PIntArray : public PBaseArray {
617  public:
623  PIntArray(
624  PINDEX initialSize = 0
625  );
626 
629  PIntArray(
630  int const * buffer,
631  PINDEX length,
632  PBoolean dynamic = true
633  );
635 };
636 #else
638 #endif
639 
640 
642 #ifdef DOC_PLUS_PLUS
643 class PLongArray : public PBaseArray {
644  public:
650  PLongArray(
651  PINDEX initialSize = 0
652  );
653 
656  PLongArray(
657  long const * buffer,
658  PINDEX length,
659  PBoolean dynamic = true
660  );
662 };
663 #else
665 #endif
666 
667 
669 #ifdef DOC_PLUS_PLUS
670 class PBYTEArray : public PBaseArray {
671  public:
677  PBYTEArray(
678  PINDEX initialSize = 0
679  );
680 
683  PBYTEArray(
684  BYTE const * buffer,
685  PINDEX length,
686  PBoolean dynamic = true
687  );
689 };
690 #else
692 #endif
693  public:
696  virtual void PrintOn(
698  ostream & strm
699  ) const;
701  virtual void ReadFrom(
702  istream &strm
703  );
705 };
706 
707 
709 #ifdef DOC_PLUS_PLUS
710 class PWORDArray : public PBaseArray {
711  public:
717  PWORDArray(
718  PINDEX initialSize = 0
719  );
720 
723  PWORDArray(
724  WORD const * buffer,
725  PINDEX length,
726  PBoolean dynamic = true
727  );
729 };
730 #else
732 #endif
733 
734 
736 #ifdef DOC_PLUS_PLUS
737 class PUnsignedArray : public PBaseArray {
738  public:
745  PINDEX initialSize = 0
746  );
747 
751  unsigned const * buffer,
752  PINDEX length,
753  PBoolean dynamic = true
754  );
756 };
757 #else
758 PSCALAR_ARRAY(PUnsignedArray, unsigned);
759 #endif
760 
761 
763 #ifdef DOC_PLUS_PLUS
764 class PDWORDArray : public PBaseArray {
765  public:
771  PDWORDArray(
772  PINDEX initialSize = 0
773  );
774 
777  PDWORDArray(
778  DWORD const * buffer,
779  PINDEX length,
780  PBoolean dynamic = true
781  );
783 };
784 #else
785 PSCALAR_ARRAY(PDWORDArray, DWORD);
786 #endif
787 
788 
790 // Linear array of objects
791 
814 {
815  PCONTAINERINFO(PArrayObjects, PCollection);
816  public:
826  PINDEX initialSize = 0
827  );
829 
859  virtual Comparison Compare(
860  const PObject & obj
861  ) const;
863 
866  virtual PINDEX GetSize() const;
868 
877  virtual PBoolean SetSize(
878  PINDEX newSize
879  );
881 
890  virtual PINDEX Append(
891  PObject * obj
892  );
893 
909  virtual PINDEX Insert(
910  const PObject & before,
911  PObject * obj
912  );
913 
924  virtual PINDEX InsertAt(
925  PINDEX index,
926  PObject * obj
927  );
928 
937  virtual PBoolean Remove(
938  const PObject * obj
939  );
940 
952  virtual PObject * RemoveAt(
953  PINDEX index
954  );
955 
963  virtual PBoolean SetAt(
964  PINDEX index,
965  PObject * val
966  );
967 
974  virtual PObject * GetAt(
975  PINDEX index
976  ) const;
977 
985  virtual PINDEX GetObjectsIndex(
986  const PObject * obj
987  ) const;
988 
998  virtual PINDEX GetValuesIndex(
999  const PObject & obj // Object to find equal of.
1000  ) const;
1001 
1008  virtual void RemoveAll();
1010 
1011  protected:
1012  // The type below cannot be nested as DevStudio 2005 AUTOEXP.DAT doesn't like it
1014 };
1015 
1016 
1024 template <class T> class PArray : public PArrayObjects
1025 {
1026  PCLASSINFO(PArray, PArrayObjects);
1027  public:
1037  PINDEX initialSize = 0
1038  ) : PArrayObjects(initialSize) { }
1040 
1046  virtual PObject * Clone() const
1047  { return PNEW PArray(0, this); }
1049 
1060  PINDEX index
1061  ) const {
1062  PObject * obj = GetAt(index);
1063  PAssert(obj != NULL, PInvalidArrayElement);
1064  return (T &)*obj;
1065  }
1067 
1068  protected:
1069  PArray(int dummy, const PArray * c) : PArrayObjects(dummy, c) { }
1070 };
1071 
1072 
1084 #define PARRAY(cls, T) typedef PArray<T> cls
1085 
1086 
1099 #define PDECLARE_ARRAY(cls, T) \
1100  PARRAY(cls##_PTemplate, T); \
1101  PDECLARE_CLASS(cls, cls##_PTemplate) \
1102  protected: \
1103  inline cls(int dummy, const cls * c) \
1104  : cls##_PTemplate(dummy, c) { } \
1105  public: \
1106  inline cls(PINDEX initialSize = 0) \
1107  : cls##_PTemplate(initialSize) { } \
1108  virtual PObject * Clone() const \
1109  { return PNEW cls(0, this); } \
1110 
1111 
1114 class PBitArray : public PBYTEArray
1115 {
1116  PCLASSINFO(PBitArray, PBYTEArray);
1117 
1118  public:
1123  PBitArray(
1124  PINDEX initialSize = 0
1125  );
1126 
1129  PBitArray(
1130  const void * buffer,
1131  PINDEX length,
1132  PBoolean dynamic = true
1133  );
1135 
1140  virtual PObject * Clone() const;
1142 
1151  virtual PINDEX GetSize() const;
1152 
1161  virtual PBoolean SetSize(
1162  PINDEX newSize
1163  );
1164 
1171  PBoolean SetAt(
1172  PINDEX index,
1173  PBoolean val
1174  );
1175 
1182  PBoolean GetAt(
1183  PINDEX index
1184  ) const;
1185 
1194  void Attach(
1195  const void * buffer,
1196  PINDEX bufferSize
1197  );
1198 
1212  BYTE * GetPointer(
1213  PINDEX minSize = 0
1214  );
1216 
1229  PINDEX index
1230  ) const { return GetAt(index); }
1231 
1238  PINDEX index
1239  ) { SetAt(index, true); return *this; }
1240 
1247  PINDEX index
1248  ) { SetAt(index, false); return *this; }
1249 
1262  const PBitArray & array
1263  );
1265 };
1266 
1267 
1268 #endif // PTLIB_ARRAY_H
1269 
1270 
1271 // End Of File ///////////////////////////////////////////////////////////////
virtual PObject * RemoveAt(PINDEX index)
Remove the object at the specified ordinal index from the collection.
PBYTEArray(PINDEX initialSize=0)
Construct a new dynamic array of unsigned chars.
virtual void PrintOn(ostream &strm) const
Print the array.
An array of objects.
Definition: array.h:813
virtual PBoolean SetAt(PINDEX index, PObject *val)
Set the object at the specified ordinal position to the new value.
virtual PINDEX GetSize() const
Get size of array.
virtual void ReadElementFrom(istream &stream, PINDEX index)
Definition: array.h:526
Array of characters.
Definition: array.h:551
T & operator[](PINDEX index) const
Retrieve a reference to the object in the array.
Definition: array.h:1059
virtual PObject * GetAt(PINDEX index) const
Get the object at the specified ordinal position.
PBitArray & operator+=(PINDEX index)
Set a bit to the array.
Definition: array.h:1237
T & operator[](PINDEX index)
Get a reference to value from the array.
Definition: array.h:398
void Attach(const void *buffer, PINDEX bufferSize)
Attach a pointer to a static block to the bit array type.
This template class maps the PAbstractArray to a specific element type.
Definition: array.h:274
PBaseArray(PINDEX initialSize=0)
Construct a new dynamic array of elements of the specified type.
Definition: array.h:285
virtual void RemoveAll()
Remove all of the elements in the collection.
void Attach(const T *buffer, PINDEX bufferSize)
Attach a pointer to a static block to the base array type.
Definition: array.h:344
void * GetPointer(PINDEX minSize=1)
Get a pointer to the internal array and assure that it is of at least the specified size...
PINLINE PArrayObjects(PINDEX initialSize=0)
Create a new array of objects.
#define PINLINE
Definition: object.h:127
#define PSCALAR_ARRAY(cls, T)
Declare a dynamic array base type.
Definition: array.h:546
PBoolean SetAt(PINDEX index, T val)
Set the specific element in the array.
Definition: array.h:316
Comparison
Result of the comparison operation performed by the Compare() function.
Definition: object.h:1184
A new or malloc failed.
Definition: object.h:152
PBoolean Concatenate(const PBitArray &array)
Concatenate one array to the end of this array.
T operator[](PINDEX index) const
Get a value from the array.
Definition: array.h:382
virtual Comparison Compare(const PObject &obj) const
Get the relative rank of the two arrays.
virtual PBoolean SetSize(PINDEX newSize)
Set the size of the array in bits.
PBoolean operator[](PINDEX index) const
Get a value from the array.
Definition: array.h:1228
virtual void ReadElementFrom(istream &stream, PINDEX index)
PScalarArray(PINDEX initialSize=0)
Construct a new dynamic array of elements of the specified type.
Definition: array.h:512
Array of unsigned long integers.
Definition: array.h:764
PLongArray(PINDEX initialSize=0)
Construct a new dynamic array of longs.
PBaseArray(T const *buffer, PINDEX length, PBoolean dynamic=true)
Construct a new dynamic array of elements of the specified type.
Definition: array.h:291
virtual PObject * Clone() const
Make a complete duplicate of the array.
Definition: array.h:1046
PWORDArray(PINDEX initialSize=0)
Construct a new dynamic array of unsigned shorts.
PCharArray(PINDEX initialSize=0)
Construct a new dynamic array of char.
virtual void PrintOn(ostream &strm) const
Print the array.
This class contains a variable length array of arbitrary memory blocks.
Definition: array.h:67
PBoolean GetAt(PINDEX index) const
Get a bit from the array.
PUnsignedArray(PINDEX initialSize=0)
Construct a new dynamic array of unsigned ints.
BOOL PBoolean
Definition: object.h:102
PIntArray(PINDEX initialSize=0)
Construct a new dynamic array of ints.
PBaseArray< PObject * > * theArray
Definition: array.h:1013
Array of unsigned characters.
Definition: array.h:670
Array of unsigned short integers.
Definition: array.h:710
void Attach(const void *buffer, PINDEX bufferSize)
Attach a pointer to a static block to the base array type.
char * theArray
Pointer to the allocated block of memory.
Definition: array.h:245
virtual void PrintOn(ostream &strm) const
Output the contents of the object to the stream.
PINDEX elementSize
Size of an element in bytes.
Definition: array.h:242
virtual PINDEX Append(PObject *obj)
Append a new object to the collection.
PBoolean SetAt(PINDEX index, PBoolean val)
Set the specific bit in the array.
virtual PINDEX GetSize() const
Get the current size of the container.
PBaseArray(PContainerReference &reference)
Definition: array.h:449
virtual PINDEX InsertAt(PINDEX index, PObject *obj)
Insert a new object at the specified ordinal index.
virtual void ReadFrom(istream &strm)
Input the contents of the object from the stream.
#define PDECLARE_BASEARRAY(cls, T)
Begin a declaration of an array of base types.
Definition: array.h:474
virtual PINDEX GetSize() const
Get the current size of the container.
Definition: contain.h:51
This class represents a dynamic bit array.
Definition: array.h:1114
virtual void PrintElementOn(ostream &stream, PINDEX index) const
Array of unsigned integers.
Definition: array.h:737
T * GetPointer(PINDEX minSize=0)
Get a pointer to the internal array and assure that it is of at least the specified size...
Definition: array.h:364
PShortArray(PINDEX initialSize=0)
Construct a new dynamic array of shorts.
Array of short integers.
Definition: array.h:589
Abstract class to embody the base functionality of a container.
Definition: contain.h:104
virtual PBoolean Remove(const PObject *obj)
Remove the object from the collection.
virtual PObject * Clone() const
Clone the object.
PBoolean InternalSetSize(PINDEX newSize, PBoolean force)
Array of long integers.
Definition: array.h:643
virtual Comparison Compare(const PObject &obj) const
Get the relative rank of the two arrays.
PArray(int dummy, const PArray *c)
Definition: array.h:1069
PBitArray & operator-=(PINDEX index)
Set a bit to the array.
Definition: array.h:1246
virtual PObject * Clone() const
Clone the object.
Definition: array.h:302
BYTE * GetPointer(PINDEX minSize=0)
Get a pointer to the internal array and assure that it is of at least the specified size...
T GetAt(PINDEX index) const
Get a value from the array.
Definition: array.h:329
PBoolean allocatedDynamically
Flag indicating the array was allocated on the heap.
Definition: array.h:248
virtual PINDEX Insert(const PObject &before, PObject *obj)
Insert a new object immediately before the specified object.
PBoolean SetMinSize(PINDEX minSize)
Set the minimum size of container.
This template class maps the PArrayObjects to a specific object type.
Definition: array.h:1024
virtual void PrintElementOn(ostream &stream, PINDEX index) const
Definition: array.h:442
#define PAssert(b, msg)
This macro is used to assert that a condition must be true.
Definition: object.h:192
This template class maps the PAbstractArray to a specific element type.
Definition: array.h:502
PArray(PINDEX initialSize=0)
Create a new array of objects.
Definition: array.h:1036
A NULL array element object was accessed.
Definition: object.h:156
virtual PBoolean SetSize(PINDEX newSize)
Set the size of the array in objects.
virtual PBoolean SetSize(PINDEX newSize)
Set the size of the array in elements.
PContainerReference * reference
Definition: contain.h:291
Array of integers.
Definition: array.h:616
PBoolean Concatenate(const PBaseArray &array)
Concatenate one array to the end of this array.
Definition: array.h:434
Ultimate parent class for all objects in the class library.
Definition: object.h:1118
A collection is a container that collects together descendents of the PObject class.
Definition: contain.h:395
virtual PINDEX GetValuesIndex(const PObject &obj) const
Search the collection for the specified value of the object.
virtual PINDEX GetObjectsIndex(const PObject *obj) const
Search the collection for the specific instance of the object.
PBitArray(PINDEX initialSize=0)
Construct a new dynamic array of bits.
PScalarArray(T const *buffer, PINDEX length, PBoolean dynamic=true)
Construct a new dynamic array of elements of the specified type.
Definition: array.h:518
PBoolean Concatenate(const PAbstractArray &array)
Concatenate one array to the end of this array.
#define PNEW
Macro for overriding system default new operator.
Definition: object.h:890
virtual void ReadFrom(istream &strm)
Read the array.
PDWORDArray(PINDEX initialSize=0)
Construct a new dynamic array of unsigned longs.
virtual void ReadFrom(istream &strm)
Read the array.
PAbstractArray(PINDEX elementSizeInBytes, PINDEX initialSize=0)
Create a new dynamic array of initalSize elements of elementSizeInBytes bytes each.