/*	XAutoPtr.h
 *
 *		Support templates that I can use that are not yet defined
 *	for me.
 */

/*  YAAF - Yet another application framework
 *  Copyright (C) 1997, 1998 William Edward Woody
 *  
 *  This library is free software; you can redistribute it
 *  and/or modify it under the terms of the GNU Library
 *  General Public License as published by the Free Software
 *  Foundation; either version 2 of the License, or any
 *  later version.
 *  
 *  This library is distributed in the hope that it will be
 *  useful, but WITHOUT ANY WARRANTY; without even the implied
 *  warranty of MERCHANTABIILITY or FITNESS FOR A PARTICULAR
 *  PURPOSE. See the GNU Library General Public License for
 *  more details.
 *  
 *  You should have received a copy of the GNU Library General
 *  Public License along with this library; if not, write to the
 *  Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 *  Boston, MA 02111-1307, USA.
 *  
 *  To contact the author, either e-mail me at woody@pandawave.com, 
 *	or write to
 *  
 *          William Edward Woody
 *          In Phase Consulting
 *          1545 Ard Eevin Avenue
 *          Glendale, CA 91202
 *
 *	Or visit us on the web at http://www.pandawave.com
 */


#ifndef PandaWave_XAUTOPTR
#define PandaWave_XAUTOPTR

#include <XConfig.h>

/************************************************************************/
/*																		*/
/*	Heap Management Stuff												*/
/*																		*/
/************************************************************************/

/*	@C"autoptr"
 *	@H"XAutoPtr.h"
 *	@I
 *
 *		Automatic pointer, like auto_ptr, except that I did it myself.
 *
 *	The rules are simple: this is a substitute for T*ptr, except that
 *	I cannot manipulate the pointer, I cannot copy to another pointer,
 *	and I must either explicitly release the pointer to the world
 *	(like TWindow objects) or return the value--both cause this pointer
 *	to become NULL.
 */

template <class T> class autoptr {
	public:
		// @G"Construction/Destruction"
		
		/*	@F"autoptr::autoptr" @I
		 *
		 *		Construction Class. This creates an automatic pointer
		 *	on the stack. This can be initialized with an object or
		 *	without.
		 */
		
		autoptr(T *ptr = NULL)		{ v = ptr; }
		
		/*	@F"autoptr::~autoptr" @I
		 *
		 *		Destruction class. If this still points to an object,
		 *	this calls the object's destructor. This makes this an
		 *	exception safe mechanism for storing temporary pointers.
		 */
		
		~autoptr()					{ if (v) delete v; }
		
		/*	@F"autoptr::operator =" @I
		 *
		 *		Initializes this with a pointer.
		 */
		
		const autoptr& operator = (T* ptr) { v = ptr; return *this; }
		
		/*
		 *	Access to pointer
		 */
		
		// @G"Access To Pointer"
		
		/*
		 *	!!!	If the compiler barfs on the next line, it's because
		 *	!!! you declared an autoptr<> with a fundamental type, such
		 *	!!! as an int, a double, or a float.
		 */
		
		/*	@F"autoptr::operator ->" @I
		 *
		 *		This emulates the normal -> operator to allow access
		 *	to fields in a class or structure.
		 */
		
		T* operator ->()			{ return v; }	// ERROR ^^^
		
		/*	@F"autoptr::operator *" @I
		 *
		 *		This emulates the normal * operator to permit access
		 *	to the contents of a class or structure.
		 */
		
		T& operator *()				{ return *v; }
		
		/*	@F"autoptr::operator !" @I
		 *
		 *		This returns true if the pointer is NULL.
		 */
		
		int operator !()			{ return (v == NULL); }

		/*	@F"autoptr::operator ==" @I
		 *
		 *		This returns true if two pointers are equal.
		 */
		
		int operator == (const T* a) { return (v == a); }

		/*	@F"autoptr::operator !=" @I
		 *
		 *		This returns true if two pointers are not equal.
		 */

		int operator != (const T* a) { return (v != a); }

		/*	@F"autoptr::operator ==" @I
		 *
		 *		This returns true if two pointers are equal.
		 */

		int operator == (const autoptr& ptr) { return (v == ptr.v); }

		/*	@F"autoptr::operator !=" @I
		 *
		 *		This returns true if two pointers are not equal.
		 */

		int operator != (const autoptr& ptr) { return (v != ptr.v); }
		
		/*
		 *	Random things I can do to this pointer
		 */
		
		// @G"Pointer Processing"
		
		/*	@F"autoptr::Detach"
		 *
		 *		Detaches this pointer. This zeros out this pointer, in
		 *	order to prevent the pointer from being returned.
		 */
		
		void Detach()				{ v = NULL; }

		/*	@F"autoptr::Return"
		 *
		 *		Returns this pointer and detaches it. This is used
		 *	when you wish to return the pointer or to put it into
		 *	another structure, detaching this.
		 */
		
		T*   Return()				{ T *a; a = v; v = NULL; return a; }

		/*	@F"autoptr::Ptr"
		 *
		 *		Returns this pointer without detaching. This is used
		 *	when you need access to the object.
		 */
		
		T*   Ptr()					{ return v; }
		
	private:
		const autoptr& operator = (const autoptr& ptr) { return ptr; } // prohibit
		
		T *v;
};

#endif // PandaWave_XAUTOPTR
