PATCH: remove_all() method added to the containers

20 Jan 2002

      Dear all,

of course there are several ways in the current version of GiNaC to erase
all the elements from a GiNaC container.  However, as far as I can tell,
they are either obscure or inefficient or both (removing one element at
a time is inefficient, assigning from an empty container is obscure and
still measurably inefficient and so forth).  Removing all the elements of
a container is a very common operation and forcing users to resort to
kludges is, I believe, not a very good idea.  Moreover, not providing
the right method for a common operation reduces the implementor's latitude
for future choices (what if you would like to use a different representation
for containers?  What if this new representation is such that the user's
kludges for erasing all the elements are seriously inefficient?)
You don't want your users to ask you whether _today_ it is best to clear
all the elements using the technique A or by the tecnique B, right?
It is not by chance that all the STL containers have a clear() method.

Enough for advocacy, please find below a patch adding a remove_all() method
to the containers.  I feel that the name "remove_all" fits well with the others.
The patch allows `make check' to complete successfully and the documentation
looks good.  I have been careful to follow your coding style.  Please let me
know if I haven't been successful and I will submit a revised patch.
All the best

      Roberto

-- 
Prof. Roberto Bagnara
Computer Science Group
Department of Mathematics, University of Parma, Italy
http://www.cs.unipr.it/~bagnara/
mailto:bagnara@cs.unipr.it

diff -rcp GiNaC-1.0.3.orig/doc/tutorial/ginac.texi GiNaC-1.0.3/doc/tutorial/ginac.texi
*** GiNaC-1.0.3.orig/doc/tutorial/ginac.texi	Fri Dec 21 12:38:03 2001
--- GiNaC-1.0.3/doc/tutorial/ginac.texi	Sat Jan 19 18:22:28 2002
*************** canonical form.
*** 1193,1198 ****
--- 1193,1199 ----
  @cindex @code{prepend()}
  @cindex @code{remove_first()}
  @cindex @code{remove_last()}
+ @cindex @code{remove_all()}

  The GiNaC class @code{lst} serves for holding a @dfn{list} of arbitrary
  expressions. These are sometimes used to supply a variable number of
*************** and @code{prepend()} methods:
*** 1230,1242 ****
      // ...
  @end example

! Finally you can remove the first or last element of a list with
  @code{remove_first()} and @code{remove_last()}:

  @example
      // ...
      l.remove_first();   // l is now @{x, 2, y, x+y, 4*x@}
      l.remove_last();    // l is now @{x, 2, y, x+y@}
  @}
  @end example

--- 1231,1251 ----
      // ...
  @end example

! You can remove the first or last element of a list with
  @code{remove_first()} and @code{remove_last()}:

  @example
      // ...
      l.remove_first();   // l is now @{x, 2, y, x+y, 4*x@}
      l.remove_last();    // l is now @{x, 2, y, x+y@}
+ @end example
+ 
+ Finally, you can remove all the elements of a list with
+ @code{remove_all()}:
+ 
+ @example
+     // ...
+     l.remove_all();   // l is now empty
  @}
  @end example

diff -rcp GiNaC-1.0.3.orig/ginac/container.pl GiNaC-1.0.3/ginac/container.pl
*** GiNaC-1.0.3.orig/ginac/container.pl	Wed Dec 19 11:54:04 2001
--- GiNaC-1.0.3/ginac/container.pl	Sat Jan 19 18:19:14 2002
*************** protected:
*** 250,255 ****
--- 250,256 ----
  public:
  	virtual ${CONTAINER} & append(const ex & b);
  	virtual ${CONTAINER} & remove_last(void);
+ 	virtual ${CONTAINER} & remove_all(void);
  ${PREPEND_INTERFACE}
  ${SORT_INTERFACE}
  protected:
*************** ${CONTAINER} & ${CONTAINER}::remove_last
*** 547,552 ****
--- 548,560 ----
  	return *this;
  }

+ ${CONTAINER} & ${CONTAINER}::remove_all(void)
+ {
+ 	ensure_if_modifiable();
+ 	seq.clear();
+ 	return *this;
+ }
+ 
  ${PREPEND_IMPLEMENTATION}

  ${SORT_IMPLEMENTATION}