COWPtr offers possibilities for more advanced usage:
Apart from the fact that COWPtr handles the copying, it has the big advantage that it forces that its access functions (ref and rwRef) are used in the correct way (ie. ref() for a const function and rwRef() for a non-const function). This ensures that copies are made when needed and not made when not needed.
Note that COWPtr uses the default constructor and the assignment operator to make a copy (thus not the copy constructor). The reason for this is that the copy constructor of some classes (e.g. Array) has reference semantics iso. copy semantics.
class String {
public:
// The constructor allocates a StringRep and hands to pointer
// to COWPtr.
String()
: itsRep (new StringRep;) {}
// This non-const function needs rwRef to make a copy when needed.
void set (const char* str) {itsRep.rwRef().set (str);}
// This const function can use ref (making a copy is not needed).
const char* get const {return itsRep.ref();}
private:
COWPtr<StringRep> itsRep;
};
class StringRep {
friend class String;
private:
void set (const char*);
const char* get() const;
char* itsData;
};
void myFunc(COWPtr<Array<Float> > &obj){
// make a nonconst from some static const Array that exists "out there"
Array<Float> &nonConstArray = (Array<Float> &)staticConstArray;
// "fill" the COWPtr and bring back constness without copying. The first
// "True" argument indicates the caller of this function may take
// control of the dynamic pointer's destruction. The second "True"
// argument indicates the array is read only and should make a copy of
// itself if writing is needed.
obj.set(new Array<Float>(nonConstArray.getSlice(...), True, True));
}
The caller of the function will get their piece of a const array without
making a copy until the last possible moment (maybe never.)
#include <casa/Utilities/COWPtr.h>
main(){
// create a null filled COWPtr
COWPtr<Array<Float> > COW;
// fill it inside myfunc
myFunc(COW);
// use a single element - still no copies have been made!
Float someVal = COW->operator()(IPosition(2,3,3))
// write to the array - now we get a copy!
COW.rwRef().set(42.0f);
// etc...
};
The dynamic "pointer to object" constructor: default behavior is to
delete the allocated memory when this instance's of COWPtr is destructed.
Or the Boolean argument of "deleteIt = False" implies the pointer is
being maintained by an object other than this instance of COWPtr and
will not delete the allocated memory upon this instance's destruction.
Control of copying is provided by the Boolean "readOnly" argument. The
default value of "readOnly = False" forces a copy if the number of
references to the dynamic memory is greater than one. Copying is always
done if the constructor is given an argument of "readOnly = True".
copy ctor with reference semantics
assignment operator with reference semantics
return a pointer to a const object. This prevents "write" operations.
return a reference to a const object. This prevents "write" operations.
Function used to change this instance of COWPtr. The pointer must be
dynamically allocated. Default behavior is to
delete the allocated memory when this instance's of COWPtr is destructed.
Or the Boolean argument of "deleteIt = False" implies the pointer is
being maintained by an object other than this instance of COWPtr and
will not delete the allocated memory upon this instance's destruction.
Control of copying is provided by the Boolean "readOnly" argument. The
default value of "readOnly = False" forces a copy if the number of
references to the dynamic memory is greater than one. Copying is always
done if the constructor is given an argument of "readOnly = True".
return a const reference to the object.
return a readable and writable reference to this instance. Instances of COWPtr constructed with argument "readOnly = True" will be made a copy. Additionally, all instances of COWPtr with more than one reference to the allocated memory stored within will be copied.
returns False if this contains a non-null ptr, otherwise, return True.
returns True if the object is const, otherwise, return False.
returns True if the object is the only instance, otherwise, return False.
Return True if copied, otherwise, False. This function will make this instance's object a copy if it is constructed with "readOnly = True." Additionally, all instances of COWPtr with more than one reference to the allocated memory stored within will be copied.