Re: [boost] API Review request: XML API for C++, second round

From: Hamish Mackenzie (hamish_at_[hidden])
Date: 2003-06-26 11:59:18

On Thu, 2003-06-26 at 16:04, Stefan Seefeld wrote:
> I don't really understand why we need three different classes to
> manage documents. In particular I don't understand why you provide
> a 'document_ptr' that is a wrapper around document_ref.

The document_ref and document_ptr would only be used when a non owning
reference or pointer is required.  Even then you could use
dom::document * and dom::document & instead in most cases.

One big difference between a reference and a pointer is that a reference
must contain a valid non null value.

dom::document_ref doc1; // Error
dom::document_ref doc2( 0 ); // Error
dom::document_ptr doc3; // Ok
dom::document_ptr doc4( 0 ); // Ok

This means you do not have to check references for null values.  A
pointer can be useful if you wish to be able to delay initialisation or
if an value is optional.

void some_function( document_ref doc ); // You must pass a doc
void some_function( document_ptr doc ); // You could pass 0

> And I don't use a 'document' class, as that is managed implicitely
> by my dom::document_ptr:
> 
> dom::document_ptr document; // create new document;
> dom::document_ptr doc(document); // create second reference to it
> dom::document_ptr doc2 = document.clone(); // clone it, i.e. make deep
>                                                copy

This is not consistent with the standard library or C++ in general.  It
will seem strange that the pointer class
1) Does not require dereferencing
2) Contains a valid and non null value after default construction
3) Has a constructor such as document_ptr( "config.xml" )
4) Has member functions such as write_to_file

The alternative would allow both...

boost::shared_ptr< dom::document > doc( new dom::document() );
boost::shared_ptr< dom::document > doc1( doc );
dom::document doc2( *doc1 );

and if the 'doc1' reference was non-owning...

dom::document doc();  // Create new doc
dom::document & doc1( doc ); // Second reference
dom::document doc2( doc1 );  // Deep copy

Again this makes it clear when reference counting is required by the
design and when it isn't.

> > Yes, you could
> > 1) define a deep copy value_type
> 
> that doesn't work as there is no way to copy nodes 'out of the
> document'.

I am not suggesting we need this but it is possible...
class node
{
  ...
private:
  document doc_;
  node_ptr node_;
};

> > 2) typedef void value_type;
> > 3) leave it undefined

-- 
Hamish Mackenzie <hamish_at_[hidden]>