From 7bababee5c7c5f419e306af93e48bb14bc980d5e Mon Sep 17 00:00:00 2001 From: Isaak Lim Date: Thu, 8 Aug 2013 09:22:50 +0000 Subject: [PATCH] updated the documentation for the improved iterators and circulators git-svn-id: http://www.openmesh.org/svnrepo/OpenMesh/trunk@915 fdac6126-5c0c-442c-9429-916003d36597 --- Doc/Tutorial/02-iterators/smooth.cc | 8 ++++---- Doc/mesh.docu | 25 +++++++++++++------------ src/OpenMesh/Core/Mesh/CirculatorsT.hh | 23 +++++++++++++++++++++-- src/OpenMesh/Core/Mesh/IteratorsT.hh | 13 +++++++++++-- 4 files changed, 49 insertions(+), 20 deletions(-) diff --git a/Doc/Tutorial/02-iterators/smooth.cc b/Doc/Tutorial/02-iterators/smooth.cc index ad8273b3..1ffe1edc 100644 --- a/Doc/Tutorial/02-iterators/smooth.cc +++ b/Doc/Tutorial/02-iterators/smooth.cc @@ -49,9 +49,9 @@ int main(int argc, char **argv) { cog[0] = cog[1] = cog[2] = valence = 0.0; - for (vv_it=mesh.vv_iter( v_it ); vv_it; ++vv_it) + for (vv_it=mesh.vv_iter( *v_it ); vv_it.is_valid(); ++vv_it) { - cog += mesh.point( vv_it ); + cog += mesh.point( *vv_it ); ++valence; } @@ -60,8 +60,8 @@ int main(int argc, char **argv) for (v_it=mesh.vertices_begin(), cog_it=cogs.begin(); v_it!=v_end; ++v_it, ++cog_it) - if ( !mesh.is_boundary( v_it ) ) - mesh.set_point( v_it, *cog_it ); + if ( !mesh.is_boundary( *v_it ) ) + mesh.set_point( *v_it, *cog_it ); } diff --git a/Doc/mesh.docu b/Doc/mesh.docu index 98ee2a69..2741c8d7 100644 --- a/Doc/mesh.docu +++ b/Doc/mesh.docu @@ -744,16 +744,16 @@ The corresponding \c const counterparts are \arg \c ConstFaceIter. -The linear iterators are (almost) conformant to STL iterators. For a +The linear iterators are conformant to STL iterators. For a description of their interface see OpenMesh::Concepts::IteratorT. -For efficiency reasons the \c operation++(int) (post-increment) -and \c operation--(int) (post-decrement) are not implemented. -Hence, when using iterators, use the pre-increment operation -(++it). -Additionally to the standard operations, each linear iterator -provides a method \c handle(), which returns the handle of the -item referred to by the iterator. +When using iterators, use the pre-increment operation (++it) for efficiency +reasons. + +\deprecated +While it is possible to use \c handle() to get the handle of the item referred +to by the iterator, this function is deprecated. Simply dereference the iterator +instead. \subsection deletedElements Deleted Elements If no elements of a mesh are marked as deleted, the indices provided by \c idx() @@ -842,9 +842,10 @@ All circulators provide the operations listed in CirculatorT, which are basically the same as the iterator funtions. -Furthermore, circulators provide \c operator \c bool(), which returns -true, as long as the circulator hasn't reached the end of the -sequence. +\deprecated +While it is possible to use \c operator \c bool(), which returns true, as long +as the circulator hasn't reached the end of the sequence, this function is +deprecated. Use the function \c is_valid() instead. %OpenMesh provides the following functions (defined in OpenMesh::PolyConnectivity) to get circulators around a specified center item: @@ -889,7 +890,7 @@ MyMesh mesh; MyMesh::FaceHalfedgeIter fh_it = mesh.fh_iter(faceHandle); -for(; fh_it; ++fh_it) { +for(; fh_it.is_valid(); ++fh_it) { std::cout << "Halfedge has handle " << *fh_it << std::endl; } diff --git a/src/OpenMesh/Core/Mesh/CirculatorsT.hh b/src/OpenMesh/Core/Mesh/CirculatorsT.hh index 8ac724bc..fe75cf12 100644 --- a/src/OpenMesh/Core/Mesh/CirculatorsT.hh +++ b/src/OpenMesh/Core/Mesh/CirculatorsT.hh @@ -314,22 +314,41 @@ class GenericCirculatorT : protected GenericCirculatorBaseT { } //DEPRECATED("current_halfedge_handle() is an implementation detail and should not be accessed from outside the iterator class.") + /** + * \deprecated + * current_halfedge_handle() is an implementation detail and should not + * be accessed from outside the iterator class. + */ const HalfedgeHandle ¤t_halfedge_handle() const { return this->heh_; } DEPRECATED("Do not use this error prone implicit cast. Compare to end-iterator or use is_valid(), instead.") + /** + * \deprecated + * Do not use this error prone implicit cast. Compare to the + * end-iterator or use is_valid() instead. + */ operator bool() const { return is_valid(); } - /// Return the handle of the current target. + /** + * \brief Return the handle of the current target. + * \deprecated + * This function clutters your code. Use dereferencing operators -> and * instead. + */ DEPRECATED("This function clutters your code. Use dereferencing operators -> and * instead.") value_type handle() const { return **this; } - /// Cast to the handle of the current target. + /** + * \brief Cast to the handle of the current target. + * \deprecated + * Implicit casts of iterators are unsafe. Use dereferencing operators + * -> and * instead. + */ DEPRECATED("Implicit casts of iterators are unsafe. Use dereferencing operators -> and * instead.") operator value_type() const { return **this; diff --git a/src/OpenMesh/Core/Mesh/IteratorsT.hh b/src/OpenMesh/Core/Mesh/IteratorsT.hh index 3a27ab04..6f86dc22 100644 --- a/src/OpenMesh/Core/Mesh/IteratorsT.hh +++ b/src/OpenMesh/Core/Mesh/IteratorsT.hh @@ -117,13 +117,22 @@ class GenericIteratorT { return &hnd_; } - /// Get the handle of the item the iterator refers to. + /** + * \brief Get the handle of the item the iterator refers to. + * \deprecated + * This function clutters your code. Use dereferencing operators -> and * instead. + */ DEPRECATED("This function clutters your code. Use dereferencing operators -> and * instead.") value_handle handle() const { return hnd_; } - /// Cast to the handle of the item the iterator refers to. + /** + * \brief Cast to the handle of the item the iterator refers to. + * \deprecated + * Implicit casts of iterators are unsafe. Use dereferencing operators + * -> and * instead. + */ DEPRECATED("Implicit casts of iterators are unsafe. Use dereferencing operators -> and * instead.") operator value_handle() const { return hnd_;