X-Git-Url: https://git.sesse.net/?a=blobdiff_plain;f=src%2Fframework%2Fmlt_deque.c;h=ca9c1a622257ca2a9a9404cd2c1dc688633ef42a;hb=86e90032adedba2a87c80f922d286c1c8742fa40;hp=6deecffaf261fedd0b492d4d8f58dab469055f25;hpb=e6c03148e1dc3b0e363c9f304b3ed93fbc1a91a9;p=mlt

diff --git a/src/framework/mlt_deque.c b/src/framework/mlt_deque.c
index 6deecffa..ca9c1a62 100644
--- a/src/framework/mlt_deque.c
+++ b/src/framework/mlt_deque.c
@@ -1,21 +1,24 @@
-/*
- * mlt_deque.c -- double ended queue
- * Copyright (C) 2003-2004 Ushodaya Enterprises Limited
- * Author: Charles Yates <charles.yates@pandora.be>
+/**
+ * \file mlt_deque.c
+ * \brief double ended queue
+ * \see mlt_deque_s
  *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
+ * Copyright (C) 2003-2009 Ushodaya Enterprises Limited
+ * \author Charles Yates <charles.yates@pandora.be>
  *
- * This program is distributed in the hope that it will be useful,
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) 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
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
  *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software Foundation,
- * Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+ * You should have received a copy of the GNU Lesser 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
  */
 
 // Local header files
@@ -25,6 +28,10 @@
 #include <stdlib.h>
 #include <string.h>
 
+/** \brief Deque entry class
+ *
+ */
+
 typedef union
 {
 	void *addr;
@@ -33,8 +40,11 @@ typedef union
 }
 deque_entry;
 
-/** Private structure.
-*/
+/** \brief Double-Ended Queue (deque) class
+ *
+ * The double-ended queue is a very versatile data structure. MLT uses it as
+ * list, stack, and circular queue.
+ */
 
 struct mlt_deque_s
 {
@@ -44,254 +54,383 @@ struct mlt_deque_s
 };
 
 /** Create a deque.
-*/
+ *
+ * \public \memberof mlt_deque_s
+ * \return a new deque
+ */
 
 mlt_deque mlt_deque_init( )
 {
-	mlt_deque this = malloc( sizeof( struct mlt_deque_s ) );
-	if ( this != NULL )
-	{
-		this->list = NULL;
-		this->size = 0;
-		this->count = 0;
-	}
-	return this;
+	mlt_deque self = calloc( 1, sizeof( struct mlt_deque_s ) );
+	return self;
 }
 
 /** Return the number of items in the deque.
-*/
+ *
+ * \public \memberof mlt_deque_s
+ * \param self a deque
+ * \return the number of items
+ */
 
-int mlt_deque_count( mlt_deque this )
+int mlt_deque_count( mlt_deque self )
 {
-	return this->count;
+	if ( self )
+		return self->count;
+	else
+		return 0;
 }
 
 /** Allocate space on the deque.
-*/
+ *
+ * \private \memberof mlt_deque_s
+ * \param self a deque
+ * \return true if there was an error
+ */
 
-static int mlt_deque_allocate( mlt_deque this )
+static int mlt_deque_allocate( mlt_deque self )
 {
-	if ( this->count == this->size )
+	if ( self->count == self->size )
 	{
-		this->list = realloc( this->list, sizeof( deque_entry ) * ( this->size + 20 ) );
-		this->size += 20;
+		self->list = realloc( self->list, sizeof( deque_entry ) * ( self->size + 20 ) );
+		self->size += 20;
 	}
-	return this->list == NULL;
+	return self->list == NULL;
 }
 
 /** Push an item to the end.
-*/
+ *
+ * \public \memberof mlt_deque_s
+ * \param self a deque
+ * \param item an opaque pointer
+ * \return true if there was an error
+ */
 
-int mlt_deque_push_back( mlt_deque this, void *item )
+int mlt_deque_push_back( mlt_deque self, void *item )
 {
-	int error = mlt_deque_allocate( this );
+	int error = mlt_deque_allocate( self );
 
 	if ( error == 0 )
-		this->list[ this->count ++ ].addr = item;
+		self->list[ self->count ++ ].addr = item;
 
 	return error;
 }
 
 /** Pop an item.
-*/
+ *
+ * \public \memberof mlt_deque_s
+ * \param self a pointer
+ * \return an opaque pointer
+ */
 
-void *mlt_deque_pop_back( mlt_deque this )
+void *mlt_deque_pop_back( mlt_deque self )
 {
-	return this->count > 0 ? this->list[ -- this->count ].addr : NULL;
+	return self->count > 0 ? self->list[ -- self->count ].addr : NULL;
 }
 
 /** Queue an item at the start.
-*/
+ *
+ * \public \memberof mlt_deque_s
+ * \param self a deque
+ * \param item an opaque pointer
+ * \return true if there was an error
+ */
 
-int mlt_deque_push_front( mlt_deque this, void *item )
+int mlt_deque_push_front( mlt_deque self, void *item )
 {
-	int error = mlt_deque_allocate( this );
+	int error = mlt_deque_allocate( self );
 
 	if ( error == 0 )
 	{
-		memmove( &this->list[ 1 ], this->list, ( this->count ++ ) * sizeof( deque_entry ) );
-		this->list[ 0 ].addr = item;
+		memmove( &self->list[ 1 ], self->list, ( self->count ++ ) * sizeof( deque_entry ) );
+		self->list[ 0 ].addr = item;
 	}
 
 	return error;
 }
 
 /** Remove an item from the start.
-*/
+ *
+ * \public \memberof mlt_deque_s
+ * \param self a pointer
+ * \return an opaque pointer
+ */
 
-void *mlt_deque_pop_front( mlt_deque this )
+void *mlt_deque_pop_front( mlt_deque self )
 {
 	void *item = NULL;
 
-	if ( this->count > 0 )
+	if ( self->count > 0 )
 	{
-		item = this->list[ 0 ].addr;
-		memmove( this->list, &this->list[ 1 ], ( -- this->count ) * sizeof( deque_entry ) );
+		item = self->list[ 0 ].addr;
+		memmove( self->list, &self->list[ 1 ], ( -- self->count ) * sizeof( deque_entry ) );
 	}
 
 	return item;
 }
 
 /** Inquire on item at back of deque but don't remove.
-*/
+ *
+ * \public \memberof mlt_deque_s
+ * \param self a deque
+ * \return an opaque pointer
+ */
 
-void *mlt_deque_peek_back( mlt_deque this )
+void *mlt_deque_peek_back( mlt_deque self )
 {
-	return this->count > 0 ? this->list[ this->count - 1 ].addr : NULL;
+	return self->count > 0 ? self->list[ self->count - 1 ].addr : NULL;
 }
 
 /** Inquire on item at front of deque but don't remove.
-*/
+ *
+ * \public \memberof mlt_deque_s
+ * \param self a deque
+ * \return an opaque pointer
+ */
 
-void *mlt_deque_peek_front( mlt_deque this )
+void *mlt_deque_peek_front( mlt_deque self )
 {
-	return this->count > 0 ? this->list[ 0 ].addr : NULL;
+	return self->count > 0 ? self->list[ 0 ].addr : NULL;
 }
 
-/** Push an item to the end.
-*/
+/** Inquire on item in deque but don't remove.
+ *
+ * \public \memberof mlt_deque_s
+ * \param self a deque
+ * \param index the position in the deque
+ * \return an opaque pointer
+ */
 
-int mlt_deque_push_back_int( mlt_deque this, int item )
+void *mlt_deque_peek( mlt_deque self, int index )
 {
-	int error = mlt_deque_allocate( this );
+	return self->count > index ? self->list[ index ].addr : NULL;
+}
+
+/** Insert an item in a sorted fashion.
+ *
+ * Optimized for the equivalent of \p mlt_deque_push_back.
+ *
+ * \public \memberof mlt_deque_s
+ * \param self a deque
+ * \param item an opaque pointer
+ * \param cmp a function pointer to the comparison function
+ * \return true if there was an error
+ */
+
+int mlt_deque_insert( mlt_deque self, void *item, mlt_deque_compare cmp )
+{
+	int error = mlt_deque_allocate( self );
 
 	if ( error == 0 )
-		this->list[ this->count ++ ].value = item;
+	{
+		int n = self->count + 1;
+		while ( --n )
+			if ( cmp( item, self->list[ n - 1 ].addr ) >= 0 )
+				break;
+		memmove( &self->list[ n + 1 ], &self->list[ n ], ( self->count - n ) * sizeof( deque_entry ) );
+		self->list[ n ].addr = item;
+		self->count++;
+	}
+	return error;
+}
+
+/** Push an integer to the end.
+ *
+ * \public \memberof mlt_deque_s
+ * \param self a deque
+ * \param item an integer
+ * \return true if there was an error
+ */
+
+int mlt_deque_push_back_int( mlt_deque self, int item )
+{
+	int error = mlt_deque_allocate( self );
+
+	if ( error == 0 )
+		self->list[ self->count ++ ].value = item;
 
 	return error;
 }
 
-/** Pop an item.
-*/
+/** Pop an integer.
+ *
+ * \public \memberof mlt_deque_s
+ * \param self a deque
+ * \return an integer
+ */
 
-int mlt_deque_pop_back_int( mlt_deque this )
+int mlt_deque_pop_back_int( mlt_deque self )
 {
-	return this->count > 0 ? this->list[ -- this->count ].value : 0;
+	return self->count > 0 ? self->list[ -- self->count ].value : 0;
 }
 
-/** Queue an item at the start.
-*/
+/** Queue an integer at the start.
+ *
+ * \public \memberof mlt_deque_s
+ * \param self a deque
+ * \param item an integer
+ * \return true if there was an error
+ */
 
-int mlt_deque_push_front_int( mlt_deque this, int item )
+int mlt_deque_push_front_int( mlt_deque self, int item )
 {
-	int error = mlt_deque_allocate( this );
+	int error = mlt_deque_allocate( self );
 
 	if ( error == 0 )
 	{
-		memmove( &this->list[ 1 ], this->list, ( this->count ++ ) * sizeof( deque_entry ) );
-		this->list[ 0 ].value = item;
+		memmove( &self->list[ 1 ], self->list, ( self->count ++ ) * sizeof( deque_entry ) );
+		self->list[ 0 ].value = item;
 	}
 
 	return error;
 }
 
-/** Remove an item from the start.
-*/
+/** Remove an integer from the start.
+ *
+ * \public \memberof mlt_deque_s
+ * \param self a deque
+ * \return an integer
+ */
 
-int mlt_deque_pop_front_int( mlt_deque this )
+int mlt_deque_pop_front_int( mlt_deque self )
 {
 	int item = 0;
 
-	if ( this->count > 0 )
+	if ( self->count > 0 )
 	{
-		item = this->list[ 0 ].value;
-		memmove( this->list, &this->list[ 1 ], ( -- this->count ) * sizeof( deque_entry ) );
+		item = self->list[ 0 ].value;
+		memmove( self->list, &self->list[ 1 ], ( -- self->count ) * sizeof( deque_entry ) );
 	}
 
 	return item;
 }
 
-/** Inquire on item at back of deque but don't remove.
-*/
+/** Inquire on an integer at back of deque but don't remove.
+ *
+ * \public \memberof mlt_deque_s
+ * \param self a deque
+ * \return an integer
+ */
 
-int mlt_deque_peek_back_int( mlt_deque this )
+int mlt_deque_peek_back_int( mlt_deque self )
 {
-	return this->count > 0 ? this->list[ this->count - 1 ].value : 0;
+	return self->count > 0 ? self->list[ self->count - 1 ].value : 0;
 }
 
-/** Inquire on item at front of deque but don't remove.
-*/
+/** Inquire on an integer at front of deque but don't remove.
+ *
+ * \public \memberof mlt_deque_s
+ * \param self a deque
+ * \return an integer
+ */
 
-int mlt_deque_peek_front_int( mlt_deque this )
+int mlt_deque_peek_front_int( mlt_deque self )
 {
-	return this->count > 0 ? this->list[ 0 ].value : 0;
+	return self->count > 0 ? self->list[ 0 ].value : 0;
 }
 
-/** Push an item to the end.
-*/
+/** Push a double float to the end.
+ *
+ * \public \memberof mlt_deque_s
+ * \param self a deque
+ * \param item a double float
+ * \return true if there was an error
+ */
 
-int mlt_deque_push_back_double( mlt_deque this, double item )
+int mlt_deque_push_back_double( mlt_deque self, double item )
 {
-	int error = mlt_deque_allocate( this );
+	int error = mlt_deque_allocate( self );
 
 	if ( error == 0 )
-		this->list[ this->count ++ ].floating = item;
+		self->list[ self->count ++ ].floating = item;
 
 	return error;
 }
 
-/** Pop an item.
-*/
+/** Pop a double float.
+ *
+ * \public \memberof mlt_deque_s
+ * \param self a deque
+ * \return a double float
+ */
 
-double mlt_deque_pop_back_double( mlt_deque this )
+double mlt_deque_pop_back_double( mlt_deque self )
 {
-	return this->count > 0 ? this->list[ -- this->count ].floating : 0;
+	return self->count > 0 ? self->list[ -- self->count ].floating : 0;
 }
 
-/** Queue an item at the start.
-*/
+/** Queue a double float at the start.
+ *
+ * \public \memberof mlt_deque_s
+ * \param self a deque
+ * \param item a double float
+ * \return true if there was an error
+ */
 
-int mlt_deque_push_front_double( mlt_deque this, double item )
+int mlt_deque_push_front_double( mlt_deque self, double item )
 {
-	int error = mlt_deque_allocate( this );
+	int error = mlt_deque_allocate( self );
 
 	if ( error == 0 )
 	{
-		memmove( &this->list[ 1 ], this->list, ( this->count ++ ) * sizeof( deque_entry ) );
-		this->list[ 0 ].floating = item;
+		memmove( &self->list[ 1 ], self->list, ( self->count ++ ) * sizeof( deque_entry ) );
+		self->list[ 0 ].floating = item;
 	}
 
 	return error;
 }
 
-/** Remove an item from the start.
-*/
+/** Remove a double float from the start.
+ *
+ * \public \memberof mlt_deque_s
+ * \param self a deque
+ * \return a double float
+ */
 
-double mlt_deque_pop_front_double( mlt_deque this )
+double mlt_deque_pop_front_double( mlt_deque self )
 {
 	double item = 0;
 
-	if ( this->count > 0 )
+	if ( self->count > 0 )
 	{
-		item = this->list[ 0 ].floating;
-		memmove( this->list, &this->list[ 1 ], ( -- this->count ) * sizeof( deque_entry ) );
+		item = self->list[ 0 ].floating;
+		memmove( self->list, &self->list[ 1 ], ( -- self->count ) * sizeof( deque_entry ) );
 	}
 
 	return item;
 }
 
-/** Inquire on item at back of deque but don't remove.
-*/
+/** Inquire on a double float at back of deque but don't remove.
+ *
+ * \public \memberof mlt_deque_s
+ * \param self a deque
+ * \return a double float
+ */
 
-double mlt_deque_peek_back_double( mlt_deque this )
+double mlt_deque_peek_back_double( mlt_deque self )
 {
-	return this->count > 0 ? this->list[ this->count - 1 ].floating : 0;
+	return self->count > 0 ? self->list[ self->count - 1 ].floating : 0;
 }
 
-/** Inquire on item at front of deque but don't remove.
-*/
+/** Inquire on a double float at front of deque but don't remove.
+ *
+ * \public \memberof mlt_deque_s
+ * \param self a deque
+ * \return a double float
+ */
 
-double mlt_deque_peek_front_double( mlt_deque this )
+double mlt_deque_peek_front_double( mlt_deque self )
 {
-	return this->count > 0 ? this->list[ 0 ].floating : 0;
+	return self->count > 0 ? self->list[ 0 ].floating : 0;
 }
 
-/** Close the queue.
-*/
+/** Destroy the queue.
+ *
+ * \public \memberof mlt_deque_s
+ * \param self a deque
+ */
 
-void mlt_deque_close( mlt_deque this )
+void mlt_deque_close( mlt_deque self )
 {
-	free( this->list );
-	free( this );
+	free( self->list );
+	free( self );
 }
-