diff options
author | Krzesimir Nowak <qdlacz@gmail.com> | 2011-01-31 20:32:21 +0100 |
---|---|---|
committer | Murray Cumming <murrayc@murrayc.com> | 2011-02-01 09:00:59 +0100 |
commit | ad59743628383374a590508d474ae81fbb74b6cd (patch) | |
tree | 9376dcda726dca4ff82bd641cce17b4fb79147dc /glib/glibmm/vectorutils.h | |
parent | a57dde3d329ec0c96b04803940c9bc844667a7b1 (diff) | |
download | glibmm-ad59743628383374a590508d474ae81fbb74b6cd.tar.gz |
Vector utils: Corrected documentation and extended it bit.
* glib/glibmm/vectorutils.h: Documented important parts of *Keeper classes
and corrected examples in *Handler classes. The documentation mostly tries
to explain memory management.
Diffstat (limited to 'glib/glibmm/vectorutils.h')
-rw-r--r-- | glib/glibmm/vectorutils.h | 173 |
1 files changed, 167 insertions, 6 deletions
diff --git a/glib/glibmm/vectorutils.h b/glib/glibmm/vectorutils.h index b724d8fc..87a91511 100644 --- a/glib/glibmm/vectorutils.h +++ b/glib/glibmm/vectorutils.h @@ -242,6 +242,28 @@ private: const GSList* node_; }; +/** A keeper class for C array. + * + * Primarily used by C++ wrappers like gtkmm. + * + * Its main purpose is to free its data when they are not needed. What will be + * destroyed depends on passed ownership upon construction. + * + * The most common usage of Glib::ArrayKeeper is getting its data when converting + * std::vector to a C array: + * @code + * void G::Temp::do_something(const std::vector<int>& v) + * { + * g_temp_do_something(gobj(), Glib::ArrayHandler<int>::vector_to_array(v).data()); + * } + * @endcode + * Variables of this class are seldom defined directly - it is mostly used as + * a temporary variable returned by Glib::ArrayHandler::vector_to_array(). + * + * Note that the usage above is correct with regards to C++ standard point 12.2.3. + * That means that data returned by data() method is valid through whole + * g_temp_do_something function and is destroyed, when this function returns. + */ template <typename Tr> class ArrayKeeper { @@ -249,10 +271,28 @@ public: typedef typename Tr::CppType CppType; typedef typename Tr::CType CType; + /** Constructs an ArrayKeeper holding @a array of size @array_size. + * @a ownership tells what should be destroyed with keeper destruction: + * <ul> + * <li>Glib::OWNERSHIP_NONE - keeper won't destroy data it holds.</li> + * <li>Glib::OWNERSHIP_SHALLOW - keeper will destroy only container it holds.</li> + * <li>Glib::OWNERSHIP_DEEP - keeper will destroy data and container it holds.</li> + * </ul> + * + * @param array - C array to hold. + * @param array_size - length of @a array. + * @param ownership - ownership definition. + */ explicit inline ArrayKeeper(const CType* array, size_t array_size, Glib::OwnershipType ownership); inline ArrayKeeper(const ArrayKeeper& keeper); ~ArrayKeeper(); + /** Gets data the keeper holds. + * + * Note that this data is owned by the keeper, so there is no need to free it. + * + * @return C array owned by ArrayKeeper. + */ inline CType* data() const; private: @@ -261,6 +301,28 @@ private: mutable Glib::OwnershipType ownership_; }; +/** A keeper class for GList. + * + * Primarily used by C++ wrappers like gtkmm. + * + * Its main purpose is to free its data when they are not needed. What will be + * destroyed depends on passed ownership upon construction. + * + * The most common usage of Glib::GListKeeper is getting its data when converting + * std::vector to a GList*: + * @code + * void G::Temp::do_something(const std::vector<int>& v) + * { + * g_temp_do_something(gobj(), Glib::ListHandler<int>::vector_to_list(v).data()); + * } + * @endcode + * Variables of this class are seldom defined directly - it is mostly used as + * a temporary variable returned by Glib::ListHandler::vector_to_list(). + * + * Note that the usage above is correct with regards to C++ standard point 12.2.3. + * That means that data returned by data() method is valid through whole + * g_temp_do_something function and is destroyed, when this function returns. + */ template <typename Tr> class GListKeeper { @@ -268,10 +330,27 @@ public: typedef typename Tr::CppType CppType; typedef typename Tr::CType CType; + /** Constructs an GListKeeper holding @a glist. + * @a ownership tells what should be destroyed with keeper destruction: + * <ul> + * <li>Glib::OWNERSHIP_NONE - keeper won't destroy data it holds.</li> + * <li>Glib::OWNERSHIP_SHALLOW - keeper will destroy only container it holds.</li> + * <li>Glib::OWNERSHIP_DEEP - keeper will destroy data and container it holds.</li> + * </ul> + * + * @param glist - GList* to hold. + * @param ownership - ownership definition. + */ explicit inline GListKeeper(const GList* glist, Glib::OwnershipType ownership); inline GListKeeper(const GListKeeper& keeper); ~GListKeeper(); + /** Gets data the keeper holds. + * + * Note that this data is owned by the keeper, so there is no need to free it. + * + * @return GList* owned by GListKeeper. + */ inline GList* data() const; private: @@ -279,6 +358,28 @@ private: mutable Glib::OwnershipType ownership_; }; +/** A keeper class for GSList. + * + * Primarily used by C++ wrappers like gtkmm. + * + * Its main purpose is to free its data when they are not needed. What will be + * destroyed depends on passed ownership upon construction. + * + * The most common usage of Glib::GSListKeeper is getting its data when converting + * std::vector to a GSList*: + * @code + * void G::Temp::do_something(const std::vector<int>& v) + * { + * g_temp_do_something(gobj(), Glib::SListHandler<int>::vector_to_slist(v).data()); + * } + * @endcode + * Variables of this class are seldom defined directly - it is mostly used as + * a temporary variable returned by Glib::SListHandler::vector_to_slist(). + * + * Note that the usage above is correct with regards to C++ standard point 12.2.3. + * That means that data returned by data() method is valid through whole + * g_temp_do_something function and is destroyed, when this function returns. + */ template <typename Tr> class GSListKeeper { @@ -286,10 +387,27 @@ public: typedef typename Tr::CppType CppType; typedef typename Tr::CType CType; + /** Constructs an GSListKeeper holding @a gslist. + * @a ownership tells what should be destroyed with keeper destruction: + * <ul> + * <li>Glib::OWNERSHIP_NONE - keeper won't destroy data it holds.</li> + * <li>Glib::OWNERSHIP_SHALLOW - keeper will destroy only container it holds.</li> + * <li>Glib::OWNERSHIP_DEEP - keeper will destroy data and container it holds.</li> + * </ul> + * + * @param gslist - GList* to hold. + * @param ownership - ownership definition. + */ explicit inline GSListKeeper(const GSList* gslist, Glib::OwnershipType ownership); inline GSListKeeper(const GSListKeeper& keeper); ~GSListKeeper(); + /** Gets data the keeper holds. + * + * Note that this data is owned by the keeper, so there is no need to free it. + * + * @return GSList* owned by GSListKeeper. + */ inline GSList* data() const; private: @@ -302,15 +420,34 @@ private: // Note that this is a struct instead of templated functions because standard template arguments // for function templates is a C++0x feature. /** A utility for converting between std::vector and plain C arrays. - * This would normally only be used by glibmm or gtkmm itself, or similar + * This would normally only be used by glibmm or gtkmm itself, or similar * libraries that wrap C APIs. * * For instance: * @code - * std::vector<TimeCoord> vec = Glib::ArrayHandler<TimeCoord, TimeCoordPtrTraits>::array_to_vector(array, array_size, Glib::OWNERSHIP_DEEP); + * std::vector<Glib::ustring> PixbufFormat::get_mime_types() const + * { + * return Glib::ArrayHandler<Glib::ustring>::array_to_vector(gdk_pixbuf_format_get_mime_types(const_cast<GdkPixbufFormat*>(gobj())), Glib::OWNERSHIP_DEEP); + * } * @endcode * or * @code + * void Display::store_clipboard(const Glib::RefPtr<Gdk::Window>& clipboard_window, guint32 time_, const std::vector<Glib::ustring>& targets) + * { + * if (!targets.size ()) + * { + * gdk_display_store_clipboard(gobj(), + * Glib::unwrap (clipboard_window), + * time_, + * Glib::ArrayHandler<Glib::ustring, AtomUstringTraits>::vector_to_array(targets).data (), + * targets.size ()); + * } + * } + * @endcode + * Note that usage below is wrong - data() returns a pointer to data owned by + * a temporary ArrayKeeper returned by vector_to_array(), which is destroyed at + * the end of this instruction. For details, see Glib::ArrayKeeper. + * @code * const char** array = Glib::ArrayHandler<Glib::ustring>::vector_to_array(vec).data (); * @endcode */ @@ -347,15 +484,27 @@ public: }; /** A utility for converting between std::vector and GList. - * This would normally only be used by glibmm or gtkmm itself, or similar + * This would normally only be used by glibmm or gtkmm itself, or similar * libraries that wrap C APIs. * * For instance: * @code - * Glib::ListHandler< Glib::RefPtr<Window> >::list_to_vector(gdk_window_get_children(gobj()), Glib::OWNERSHIP_SHALLOW); + * std::vector< Glib::RefPtr<Window> > Window::get_children() + * { + * return Glib::ListHandler<Glib::RefPtr<Window> >::list_to_vector(gdk_window_get_children(gobj()), Glib::OWNERSHIP_SHALLOW); + * } * @endcode * or * @code + * void Window::set_icon_list(const std::vector< Glib::RefPtr<Gdk::Pixbuf> >& pixbufs) + * { + * gdk_window_set_icon_list(gobj(), Glib::ListHandler<Glib::RefPtr<Gdk::Pixbuf> >::vector_to_list(pixbufs).data ()); + * } + * @endcode + * Note that usage below is wrong - data() returns a pointer to data owned by + * a temporary ListKeeper returned by vector_to_list(), which is destroyed at + * the end of this instruction. For details, see Glib::ListKeeper. + * @code * GList* glist = Glib::ListHandler<Glib::RefPtr<Gdk::Pixbuf> >::vector_to_list(pixbufs).data(); * @endcode */ @@ -375,15 +524,27 @@ public: }; /** A utility for converting between std::vector and GSList. - * This would normally only be used by glibmm or gtkmm itself, or similar + * This would normally only be used by glibmm or gtkmm itself, or similar * libraries that wrap C APIs. * * For instance: * @code - * std::vector< Glib::RefPtr<Display> > vec = Glib::SListHandler<Glib::RefPtr<Display> >::slist_to_vector(gdk_display_manager_list_displays(gobj()), Glib::OWNERSHIP_SHALLOW); + * std::vector< Glib::RefPtr<Display> > DisplayManager::list_displays() + * { + * return Glib::SListHandler<Glib::RefPtr<Display> >::slist_to_vector(gdk_display_manager_list_displays(gobj()), Glib::OWNERSHIP_SHALLOW); + * } * @endcode * or * @code + * void Stuff::set_slist(const std::vector<int>& ints) + * { + * g_stuff_set_slist(gobj(), Glib::SListHandler<int>::vector_to_slist(ints).data ()); + * } + * @endcode + * Note that usage below is wrong - data() returns a pointer to data owned by + * a temporary SListKeeper returned by vector_to_slist(), which is destroyed at + * the end of this instruction. For details, see Glib::SListKeeper. + * @code * GSList* gslist = Glib::SListHandler< Glib::RefPtr<Display> >::vector_to_slist(vec).data(); * @endcode */ |