Table of Contents
Table of Contentsclass PtSetWhen PTXX encounters a declaration for a set that contains non-persistent objects or C++ base types it derives it from PtSet. These objects do not have object identity, so elements read from PtSets are simply copied directly. When PtSet copies an object into or out of the set, it simply uses memcpy(). Assignment operators or copy constructors are ignored. Therefore, you should be very careful about using non-persistent objects in sets. You may safely use sets of POET's base types, such as PtString, since the type manager is aware of them and handles them appropriately.
Many of the functions use void pointers. When you actually use the class, though, you use a class which is generated by PTXX, and in the generated class the void pointer interface is replaced by a type-safe interface. For instance, if you declare your set like this:
then NonPersClass is the type of the set's elements, and PTXX will generate a set class which contains NonPersClass elements. In the function listings in this chapter, we list the functions with the native PtSet interface, e.g:
| Append | inline int Append(void* ElemAddr); |
| Get | inline int Get(void* ElemAddr); |
| Insert | inline int Insert(void* ElemAddr); |
| Put | inline int Put(void* ElemAddr); |
| Unget | inline int Unget(void* ElemAddr); |
If your set contains NonPersClass objects, the set generated by PTXX will have functions like this, which are the functions you will actually use:
| Append | inline int Append(NonPersClass& Elem); |
| Get | inline int Get(NonPersClass& Elem); |
| Insert | inline int Insert(NonPersClass& Elem); |
| Put | inline int Put(NonPersClass& Elem); |
| Unget | inline int Unget(NonPersClass& Elem); |
Please read the chapter "Sets" for general guidelines on declaring and programming with sets. Set declaration syntax is explained in the chapter "The PTXX Precompiler."
Unlike POET's other set types, PtSet is not derived from PtObjectSet, since PtSet contains non-persistent objects and base types, and PtObjectSet manages objects using the object identities which only persistent objects have.
PtSet: class summary| Files to include | Class declaration | Base class |
| poet.hxx | ptset.hxx | none |
| constructor | PtSet(PtAccessMethod AM, PtBase* database)); |
| destructor | virtual ~PtSet(); |
| Append | inline int Append(void* ElemAddr); |
| Assign | virtual void Assign(PtBase* oa); |
| Clear | virtual int Clear() = 0; |
| Delete | virtual int Delete() = 0; |
| Get | inline int Get(void* ElemAddr); |
| GetAccMethod | virtual PtAccessMethod GetAccMethod(); |
| GetBase | virtual PtBase* GetBase(); |
| GetClassId | virtual PtClassId& GetClassId(); |
| GetCurrentPos | virtual long GetCurrentPos() = 0; |
| GetElemSize | virtual word GetElemSize() = 0; |
| GetMetaType | virtual PtMetaSet* GetMetaType(); |
| GetNum | virtual dword GetNum() = 0; |
| GetSetType | virtual PtSetType GetSetType(); |
| Insert | inline int Insert(void* ElemAddr); |
| IsAssigned | inline bool IsAssigned(); |
| Make | static PtSet* Make(PtBase* , const PtString& ClassName, PtSetType); |
| Put | inline int Put(void* ElemAddr); |
| Seek | virtual int Seek(long, PtSeekMode) = 0; |
| Unget | inline int Unget(void* ElemAddr); |
PtSet::PtSet() - PtSet::PtSet() PtSet::PtSet(PtBase* pb)
| pb | The identifier of the current database. |
These are the constructors for a set. The second form assigns the set to a database, which is necessary if you want to use the set for queries or sorts. If you construct a set using the first form then you can assign it to a database later using the PtSet:: Assign().
Note: You will not usually call these constructors directly. If the set is part of a persistent object then PTXX automatically defines your set type and derives it from the proper base types so that the right constructor will be called.
PtSet::~PtSet() - virtual PtSet::~PtSet()
- int PtSet::Append(void* Elem)
Appends an element to the end of the set.
| void* Elem | Address of the element to be appended. |
The current internal position does not change. A non-zero return value indicates an error.
PtSet::Assign() - void PtSet::Assign(PtBase* pb)
Assigns the set to a database.
| pb | Database identifier. |
It is not usually necessary to use this method unless you are using sets that are not members of persistent objects. If a set is read from the database then it is automatically assigned. If a set is a member of a persistent object then it is assigned when that object is stored. A non-zero return value indicates an error.
PtSet::Clear() - int PtSet::Clear()
Removes all elements from the set. A non-zero return value indicates an error.
PtSet::Delete() - int PtSet::Delete()
Deletes the current element from the set.
The internal position is unchanged, but it now contains the next element. If you delete the last element in the set then the internal position is undefined. A non-zero return value indicates an error.
PtSet::Get() - int PtSet::Get(void* Elem)
| void* Elem | Address of the new element |
Copies the element from the set. When you are done with the element, use Unget() to free up its resources.
Any non-zero return value indicates an error.
PtSet::GetAccMethod() - virtual PtAccessMethod PtSet::GetAccMethod()
Returns the access method for the set. A PtAccessMethod is an enum which may take the following values:
| PtDIRECT | The set contains non-persistent objects or C++ base types |
| PtINDIRECT | The set contains pointers to persistent objects |
For a PtSet, the access method is always PtDIRECT.
PtSet::GetBase() - virtual PtBase* PtSet::GetBase()
If the set is assigned to a database, returns a pointer to the PtBase to which it is assigned. Otherwise, returns zero.
PtSet::GetClassId() - virtual PtClassId& PtSet::GetClassId()
Returns the PtClassId for the set.
PtSet::GetCurrentPos() - virtual long PtSet::GetCurrentPos() = 0
Returns the current seek position in the set.
PtSet::GetElemSize() - virtual word PtSet::GetElemSize() = 0
Returns the number of bytes occupied by one element in the set.
PtSet::GetMetaType() - virtual PtMetaSet* PtSet::GetMetaType()
Returns the PtMetaSet which describes this set in the class dictionary. PtMetaSet is described in the Generic Programming Guide.
PtSet::GetNum() - dword PtSet::GetNum() = 0
Returns the number of elements contained in the set.
PtSet::GetSetType() - virtual PtSetType PtSet::GetSetType()
Returns the set type for the set. A PtSetType may be:
| PtCSET | The set is a cset. |
| PtLSET | The set is an lset. |
| PtHSET | The set is an hset. |
| PtALLSET | The set is an AllSet |
Obviously, a PtSet will never be an AllSet.
PtSet::Insert() - int PtSet::Insert(void* Elem)
Inserts the item at the current internal position.
| void* Elem | Address of the element to be inserted. |
After completion the internal position contains the newly inserted item. Any non-zero return value indicates an error.
PtSet::IsAssigned() - inline bool PtSet::IsAssigned()
Returns a non-zero value if the set has been assigned to a database.
PtSet::Make() - static PtSet* PtSet::Make(PtBase* , const PtString& ClassName, PtSetType)
Creates a set to contain objects of the given class, C++ base type, or type manager type, and assigns the set to the database. Since this is a static function, you do not need to create a PtSet to call this function.
| PtBase* pBase | The database to which the set should be assigned |
| const PtString& PtObjectSet | The name of the class that the set should contain |
| PtSetType type | PtCSET, PtLSET, PtHSET, or PtALLSET |
A pointer to the new set. If the set could not be created, returns 0.
PtSet::Put() - int PtSet::Put(void* Elem)
Overwrites the current element.
| Parameters: | |
| void* Elem | Address of the element to be put at the current position. |
The Element at the current internal position is overwritten by Elem. The current internal position remains unchanged.
The type of Elem must match the declaration in your .hcd file. Note: When you change a non-persistent object or a C++ base type then you should use Put() to rewrite it. This is not necessary for PtObjectSets because POET keeps track of the object references and updates the object automatically. Since PtSets have no object identity you must Put() the revised object to the set.
Any non-zero return value indicates an error.
PtSet::Seek() - int PtSet::Seek(long Offset, PtSeekMode RelativeTo) = 0
Sets the internal position for the set.
| Offset | Number of objects. If negative, .will position backwards. |
| RelativeTo | PtSTART, PtEND or PtCURRENT. |
This function is analogous to the standard lseek() function, but Offset is measured in elements instead of bytes. If Offset is 12 and RelativeTo is PtSTART then Seek() sets the internal position to the 12th object from the start of the set. Negative offsets are used when positioning backwards within the set.
Any non-zero return value indicates an error.
PtSet::Unget() - int PtSet::Unget(void* Elem)
Frees up resources associated with an element.
| void* Elem | Address of the element to unget. |
PtSet:: Get() must allocate resources if it loads an element into memory. PtSet:: Unget() returns these resources.
In the current implementation of POET this method does nothing at all. Future versions of POET may do more.
OK, to be completely honest with you, you don't really have to use PtSet:: Unget(). Any PtSet function which reads from the set takes a parameter by reference, which means that the PtSet does not create new objects - you create an empty object, and read it from the set. Therefore, there is no real need for PtSet:: Unget(). This function exists for symmetry with PtObjectSets, but you don't have to use it.
Any non-zero result indicates an error.
Copyright (c) 1996 POET Software, Inc. All rights reserved. Reproduction in whole or in part in any form or medium without the express permission of POET Software, Inc. is prohibited.