eina_cxx: add documentation to the Eina C++ header files.

Summary:
Added documentation to almost all classes that are intended for direct use by the library users.
Marked classes/functions used by the library itself as @internal.
Modified the Doxyfile.in to enable the generation of documentation to the bindings.

Reviewers: felipealmeida, cedric, woohyun, smohanty, raster

CC: savio, cedric

Differential Revision: https://phab.enlightenment.org/D947

Signed-off-by: Cedric BAIL <c.bail@partner.samsung.com>
devs/raoul/macos_port
vitor.sousa 9 years ago committed by Cedric BAIL
parent 5e7a9b1225
commit 0902b6a6f8
  1. 4
      doc/Doxyfile.in
  2. 44
      src/bindings/eina_cxx/Eina.hh
  3. 298
      src/bindings/eina_cxx/eina_accessor.hh
  4. 58
      src/bindings/eina_cxx/eina_clone_allocators.hh
  5. 155
      src/bindings/eina_cxx/eina_error.hh
  6. 1118
      src/bindings/eina_cxx/eina_inarray.hh
  7. 610
      src/bindings/eina_cxx/eina_inlist.hh
  8. 46
      src/bindings/eina_cxx/eina_integer_sequence.hh
  9. 144
      src/bindings/eina_cxx/eina_iterator.hh
  10. 16
      src/bindings/eina_cxx/eina_lists_auxiliary.hh
  11. 229
      src/bindings/eina_cxx/eina_log.hh
  12. 233
      src/bindings/eina_cxx/eina_optional.hh
  13. 670
      src/bindings/eina_cxx/eina_ptrarray.hh
  14. 704
      src/bindings/eina_cxx/eina_ptrlist.hh
  15. 294
      src/bindings/eina_cxx/eina_range_types.hh
  16. 53
      src/bindings/eina_cxx/eina_ref.hh
  17. 331
      src/bindings/eina_cxx/eina_stringshare.hh
  18. 454
      src/bindings/eina_cxx/eina_thread.hh
  19. 20
      src/bindings/eina_cxx/eina_type_traits.hh
  20. 252
      src/bindings/eina_cxx/eina_value.hh

@ -594,6 +594,7 @@ WARN_LOGFILE =
# with spaces.
INPUT = @top_srcdir@/src/lib \
@top_srcdir@/src/bindings \
@srcdir@/main.dox \
@srcdir@/pkgconfig.dox \
@srcdir@/eina_examples.dox \
@ -626,7 +627,8 @@ INPUT_ENCODING = UTF-8
FILE_PATTERNS = *.c \
*.h \
*.x
*.x \
*.hh
# The RECURSIVE tag can be used to turn specify whether or not subdirectories
# should be searched for input files as well. Possible values are YES and NO.

@ -1,6 +1,11 @@
#ifndef EINA_HH_
#define EINA_HH_
/**
* @file
* @brief Eina C++
*/
#include <eina_iterator.hh>
#include <eina_ptrarray.hh>
#include <eina_ptrlist.hh>
@ -16,8 +21,37 @@
#include <eina_optional.hh>
#include <eina_integer_sequence.hh>
/**
* @defgroup Eina_Cxx Eina C++
*
* @defgroup Eina_Cxx_Data_Types_Group Data Types
* @ingroup Eina_Cxx
*
* @defgroup Eina_Cxx_Content_Access_Group Content Access
* @ingroup Eina_Cxx_Data_Types_Group
*
* @defgroup Eina_Cxx_Containers_Group Containers
* @ingroup Eina_Cxx_Data_Types_Group
*
* @defgroup Eina_Cxx_Tools_Group Tools
* @ingroup Eina_Cxx
*
*/
namespace efl { namespace eina {
/**
* @addtogroup Eina_Cxx
*
* @{
*/
/**
* @brief Initialize the Eina library.
*
* Initialize all the Eina modules upon construction and finalize them
* upon destruction, using the RAII programming idiom.
*/
struct eina_init
{
eina_init()
@ -30,6 +64,12 @@ struct eina_init
}
};
/**
* @brief Initialize the mutexes of the Eina library.
*
* Set up all the mutexes in all Eina modules upon construction and
* shut them down upon destruction, using the RAII programming idiom.
*/
struct eina_threads_init
{
eina_threads_init()
@ -42,6 +82,10 @@ struct eina_threads_init
}
};
/**
* @}
*/
} }
#endif

@ -9,25 +9,82 @@
#include <cstdlib>
#include <cassert>
/**
* @addtogroup Eina_Cxx_Content_Access_Group
*
* @{
*/
namespace efl { namespace eina {
/**
* @defgroup Eina_Cxx_Accessor_Group Accessor
* @ingroup Eina_Cxx_Content_Access_Group
*
* @brief These classes manage accessor on containers.
*
* These classes allow to access elements of a container in a
* generic way, without knowing which container is used (like
* iterators in the C++ STL). Accessors allows random access (that is, any
* element in the container). For sequential access, see
* @ref Eina_Cxx_Iterator_Group.
*
* @{
*/
/**
* Wraps an native Eina_Accessor and provide random access to data structures.
*/
template <typename T>
struct accessor
{
typedef unsigned int key_type;
typedef T mapped_type;
typedef T value_type;
typedef std::size_t size_type;
typedef unsigned int key_type; /**< Type for accessor key. */
typedef T mapped_type; /**< Type for accessor mapped elements. */
typedef T value_type; /**< Type for accessor elements. Same as @ref mapped_type. */
typedef std::size_t size_type; /**< Type for size information used in the accessor. */
/**
* @brief Default constructor. Creates an empty accessor.
*/
accessor() : _impl(0) {}
/**
* @brief Create an accessor object that wraps the given Eina accessor.
* @param impl Native @c Eina_Accessor to be wrapped.
*
* This constructor creates an accessor object that wraps the given
* Eina_Accessor and provides access to the data pointed by it.
*
* @warning It is important to note that the created accessor object
* gains ownership of the given handle, deallocating it at destruction
* time.
*/
explicit accessor(Eina_Accessor* impl)
: _impl(impl)
{
assert(_impl != 0);
}
/**
* @brief Copy constructor. Creates a copy of the given accessor object.
* @param other Other accessor object.
*
* This constructor clones the internal @c Eina_Accessor of the given
* accessor object, so that the newly created object can be used
* freely.
*/
accessor(accessor<T> const& other)
: _impl(eina_accessor_clone(other._impl))
{}
/**
* @brief Assignment Operator. Replace the current content.
* @param other Other accessor object.
* @throw <tt>eina::system_error</tt> if the Eina accessor could not be cloned.
*
* This operator replaces the current native Eina accessor by a copy
* of the native accessor inside the given object.
*/
accessor<T>& operator=(accessor<T> const& other)
{
eina_accessor_free(_impl);
@ -36,11 +93,25 @@ struct accessor
throw eina::system_error(efl::eina::get_error_code(), "Error cloning accessor");
return *this;
}
/**
* @brief Destructor. Free the internal @c Eina_Acessor.
*/
~accessor()
{
eina_accessor_free(_impl);
}
/**
* @brief Retrieve the data of the accessor at a given position.
* @param i The position of the element.
* @return Constant reference to the retrieved data.
* @throw <tt>eina::system_error</tt> if the given element could not be retrieved.
*
* This operator retrieves a constant reference to the element at the
* given position. If the element could not be retrieved an
* <tt>eina::system_error</tt> is thrown.
*/
mapped_type& operator[](size_type i) const
{
assert(_impl != 0);
@ -53,98 +124,242 @@ struct accessor
return *static_cast<mapped_type*>(p);
}
/**
* @brief Get the handle for the wrapped @c Eina_Accessor.
* @return Internal handle for the native Eina accessor.
*
* This member function returns the native @c Eina_Accessor handle
* that is wrapped inside this object.
*
* @warning It is important to take care when using it, since the
* handle will be automatically release upon object destruction.
*/
Eina_Accessor* native_handle() const;
/**
* @brief Swap content between both objects.
* @param other Other accessor object.
*
* This member function swaps the internal @c Eina_Acessor with the
* given accessor object.
*/
void swap(accessor<T>& other)
{
std::swap(_impl, other._impl);
}
/**
* @brief Cast to @c boolean based on the wrapped @c Eina_Accessor.
* @return @c true if the wrapped handle is not @c NULL, @c false otherwise.
*
* Boolean typecast overload for easy validation of the accessor
* object. Returns @c false if it does not have an internal
* @c Eina_Accessor, i.e. if the current handle is not @c NULL.
*/
explicit operator bool() const
{
return native_handle() ? &accessor<T>::native_handle : 0 ;
}
private:
/**
* @internal
* Member variable for storing the native Eina_Accessor pointer.
*/
Eina_Accessor* _impl;
};
/**
* @brief Swap the contents of the two accessor objects.
* @param lhs First accessor object.
* @param rhs Second accessor object.
*/
template <typename U>
void swap(accessor<U>& lhs, accessor<U>& rhs)
{
lhs.swap(rhs);
}
/**
* @}
*/
/**
* @defgroup Eina_Cxx_Accessor_Iterator_Group Accessor Iterator
* @ingroup Eina_Cxx_Content_Access_Group
*
* @{
*/
/**
* Random access iterator for <tt>eina::accessor</tt>.
*/
template <typename T>
struct accessor_iterator
{
typedef T value_type;
typedef value_type* pointer;
typedef value_type& reference;
typedef std::ptrdiff_t difference_type;
typedef std::random_access_iterator_tag iterator_category;
typedef T value_type; /**< Type of the elements. */
typedef value_type* pointer; /**< Pointer to element type. */
typedef value_type& reference; /**< Reference to element type. */
typedef std::ptrdiff_t difference_type; /**< Type to represent the distance between two @ref accessor_iterators */
typedef std::random_access_iterator_tag iterator_category; /**< Defines the iterator as being a random access iterator. */
/**
* @brief Creates an @c accessor_iterator to the given <tt>eina::accessor</tt>.
* @param a <tt>eina::accessor</tt> object.
* @param pos Initial position of the iterator (Default = @c 0).
*
* This constructor creates an @c accessor_iterator for the given
* <tt>eina::accessor</tt> object. The position initially pointed by
* the iterator can be supplied via the @p pos argument, by default
* it is the first position (index @c 0).
*/
accessor_iterator(accessor<T> const& a, unsigned int pos = 0u)
: _accessor(a), _index(pos)
{}
/**
* @brief Move the iterator forward by @p i positions.
* @param i Number of positions to move.
* @return The @c accessor_iterator itself.
*/
accessor_iterator<T>& operator+=(difference_type i)
{
_index += i;
return *this;
}
/**
* @brief Move the iterator back by @p i positions.
* @param i Number of positions to move.
* @return The @c accessor_iterator itself.
*/
accessor_iterator<T>& operator-=(difference_type i)
{
_index -= i;
return *this;
}
/**
* @brief Get the element @p i positions away from the current element.
* @param i Position relative to the current element.
* @return Reference to the element @p i positions away from the
* element currently pointed by the @c accessor_iterator.
*/
value_type& operator[](difference_type i)
{
return _accessor[_index + i];
}
/**
* @brief Move the iterator to the next position.
* @return The @c accessor_iterator itself.
*
* This operator increments the iterator, making it point to the
* position right after the current one.
* At the end, it returns a reference to itself.
*/
accessor_iterator<T>& operator++()
{
++_index;
return *this;
}
/**
* @brief Move the iterator to the previous position.
* @return The @c accessor_iterator itself.
*
* This operator decrements the iterator, making it point to the
* position right before the current one.
* At the end, it returns a reference to itself.
*/
accessor_iterator<T>& operator--()
{
--_index;
return *this;
}
/**
* @brief Move the iterator to the next position.
* @return A copy of the @c accessor_iterator before the change.
*
* This operator increments the iterator, making it point to the
* position right after the current one.
* At the end, it returns a copy of the @c accessor_iterator before
* the change.
*/
accessor_iterator<T>& operator++(int)
{
accessor_iterator<T> tmp(*this);
++*this;
return tmp;
}
/**
* @brief Move the iterator to the previous position.
* @return A copy of the @c accessor_iterator before the change.
*
* This operator decrements the iterator, making it point to the
* position right before the current one.
* At the end, it returns a copy of the @c accessor_iterator before
* the change.
*/
accessor_iterator<T>& operator--(int)
{
accessor_iterator<T> tmp(*this);
--*this;
return tmp;
}
/**
* @brief Get a reference to the element currently pointed by the @c accessor_iterator.
* @return Reference to the current element.
*/
value_type& operator*() const
{
return _accessor[_index];
}
/**
* @brief Return a pointer to the current element, which member will be accessed.
* @return Pointer to the element currently pointed by the @c accessor_iterator.
*/
pointer operator->() const
{
return &**this;
}
/**
* @brief Swap content with the given @c accessor_iterator.
* @param other Another @c accessor_iterator of the same type.
*/
void swap(accessor_iterator<T>& other)
{
std::swap(_index, other._index);
std::swap(_accessor, other._accessor);
}
private:
accessor<T> _accessor;
unsigned int _index;
accessor<T> _accessor; /**< @internal */
unsigned int _index; /**< @internal */
/**
* @brief Check if @p lhs and @p rhs point to the same position.
* @param lhs @c accessor_iterator at the left side of the expression.
* @param rhs @c accessor_iterator at the right side of the expression.
* @return @c true if both @p lhs and @p rhs point to the same position.
*/
template <typename U>
friend bool operator==(accessor_iterator<U> const& lhs, accessor_iterator<U> const& rhs)
{
return lhs._index == rhs._index;
}
/**
* @brief Get the distance between two <tt>accessor_iterator</tt>s.
* @param lhs @c accessor_iterator at the left side of the expression.
* @param rhs @c accessor_iterator at the right side of the expression.
* @return The number of elements between @p lhs and @p rhs.
*/
template <typename U>
friend typename accessor_iterator<U>::difference_type
operator-(accessor_iterator<U> const& lhs, accessor_iterator<U> const& rhs)
@ -152,6 +367,12 @@ private:
return lhs._index - rhs._index;
}
/**
* @brief Get an @c accessor_iterator moved @p rhs positions forward.
* @param lhs @c accessor_iterator object.
* @param rhs Number of positions relative to the current element.
* @return Copy of @p lhs moved @p rhs positions forward.
*/
template <typename U>
friend
accessor_iterator<U> operator+(accessor_iterator<U> lhs
@ -161,6 +382,12 @@ private:
return lhs;
}
/**
* @brief Get an @c accessor_iterator moved @p lhs positions forward.
* @param lhs Number of positions relative to the current element.
* @param rhs @c accessor_iterator object.
* @return Copy of @p rhs moved @p lhs positions forward.
*/
template <typename U>
friend
accessor_iterator<U> operator+(typename accessor_iterator<U>::difference_type lhs
@ -169,12 +396,26 @@ private:
return rhs + lhs;
}
/**
* @brief Check if @p lhs points to a position before the position pointed by @p rhs.
* @param lhs @c accessor_iterator at the left side of the expression.
* @param rhs @c accessor_iterator at the right side of the expression.
* @return @c true if @p lhs points to a position before the position
* pointed by @p rhs, @c false otherwise.
*/
template <typename U>
friend bool operator<(accessor_iterator<U> const& lhs, accessor_iterator<U> const& rhs)
{
return lhs._index < rhs._index;
}
/**
* @brief Check if the position pointed by @p lhs is the same or is before the one pointed by @p rhs.
* @param lhs @c accessor_iterator at the left side of the expression.
* @param rhs @c accessor_iterator at the right side of the expression.
* @return @c true if the position pointed by @p lhs is the same or is
* before the position pointed by @p rhs, @c false otherwise.
*/
template <typename U>
friend bool operator<=(accessor_iterator<U> const& lhs, accessor_iterator<U> const& rhs)
{
@ -182,30 +423,63 @@ private:
}
};
/**
* @brief Check if the position pointed by @p lhs is the same or is after the one pointed by @p rhs.
* @param lhs @c accessor_iterator at the left side of the expression.
* @param rhs @c accessor_iterator at the right side of the expression.
* @return @c true if the position pointed by @p lhs is the same or is
* after the position pointed by @p rhs, @c false otherwise.
*/
template <typename U>
bool operator>=(accessor_iterator<U> const& lhs, accessor_iterator<U> const& rhs)
{
return !(lhs < rhs);
}
/**
* @brief Check if @p lhs points to a position after the position pointed by @p rhs.
* @param lhs @c accessor_iterator at the left side of the expression.
* @param rhs @c accessor_iterator at the right side of the expression.
* @return @c true if @p lhs points to a position after the position
* pointed by @p rhs, @c false otherwise.
*/
template <typename U>
bool operator>(accessor_iterator<U> const& lhs, accessor_iterator<U> const& rhs)
{
return !(lhs <= rhs);
}
/**
* @brief Check if @p lhs and @p rhs point to different positions.
* @param lhs @c accessor_iterator at the left side of the expression.
* @param rhs @c accessor_iterator at the right side of the expression.
* @return @c true if @p lhs and @p rhs point to different positions.
*/
template <typename U>
bool operator!=(accessor_iterator<U> const& lhs, accessor_iterator<U> const& rhs)
{
return !(lhs == rhs);
}
/**
* @brief Swap content between two <tt>accessor_iterator</tt>s.
* @param lhs First @c accessor_iterator.
* @param rhs Second @c accessor_iterator.
*/
template <typename U>
void swap(accessor_iterator<U>& lhs, accessor_iterator<U>& rhs)
{
lhs.swap(rhs);
}
/**
* @}
*/
} }
/**
* @}
*/
#endif

@ -6,8 +6,31 @@
#include <cstdlib>
#include <type_traits>
/**
* @addtogroup Eina_Cxx_Containers_Group
*
* @{
*/
namespace efl { namespace eina {
/**
* @defgroup Eina_Cxx_Clone_Allocators_Group Clone Allocators
* @ingroup Eina_Cxx_Containers_Group
*
* Clone allocators is a formalized way to pointer containers control
* the memory of the stored objects, allowing users to apply custom
* allocators/deallocators for the cloned objects.
*
* @{
*/
/**
* This allocator creates copies of objects on the heap, calling their
* copy constructor to make then equivalent to the given reference.
*
* The created objects are released with the default delete.
*/
struct heap_copy_allocator
{
template <typename T>
@ -27,6 +50,11 @@ struct heap_copy_allocator
}
};
/**
* This allocator allows users to create custom allocation schemes by
* overloading the <tt>new_clone(T const& v)</tt> and
* <tt>delete_clone(T* p)</tt> functions.
*/
struct heap_clone_allocator
{
template <typename T>
@ -41,6 +69,14 @@ struct heap_clone_allocator
}
};
/**
* This allocator does not allocate or deallocate anything. It simple
* gets non-const-qualified pointers for objects, which allow
* containers to hold elements without having ownership on them.
*
* It is commonly used to create a pointer container that is a view into
* another existing container.
*/
struct view_clone_allocator
{
template <typename T>
@ -54,6 +90,11 @@ struct view_clone_allocator
}
};
/**
* This allocator does not define an @c allocate_clone member function,
* so it should be used to disable operations that require elements to
* be cloned.
*/
struct heap_no_copy_allocator
{
template <typename T>
@ -65,8 +106,15 @@ struct heap_no_copy_allocator
delete p;
#endif
}
};
};
/**
* Manages allocation and deallocation of memory using the function
* @c malloc and @c free. This allocator does not calls constructors,
* the content of the newly allocated objects are assigned using
* @c memcpy, so it is likely only plausible with types that have
* <em>standard-layout</em>.
*/
struct malloc_clone_allocator
{
template <typename T>
@ -86,6 +134,14 @@ struct malloc_clone_allocator
}
};
/**
* @}
*/
} }
/**
* @}
*/
#endif

@ -5,48 +5,129 @@
#include <system_error>
/**
* @addtogroup Eina_Cxx_Tools_Group
*
* @{
*/
namespace efl { namespace eina {
/**
* @defgroup Eina_Cxx_Error_Group Error Handling
* @ingroup Eina_Cxx_Tools_Group
*
* @brief Functions for handling Eina errors.
*
* Integrates the Eina errors with the standard error representation
* defined in the @c system_error library.
*
* @{
*/
/** <tt>std::errc</tt> for Eina errors. */
using std::errc;
/** <tt>std::system_error</tt> for Eina errors. */
using std::system_error;
/** <tt>std::error_code</tt> for Eina errors. */
using std::error_code;
/** <tt>std::error_condition</tt> for Eina errors. */
using std::error_condition;
/** <tt>std::error_category</tt> for Eina errors. */
typedef std::error_category system_error_category;
/**
* @brief Return a @c Eina_Error for an unknown error.
* @return @c Eina_Error indicating a unknown/external error condition.
*
* This function returns an @c Eina_Error indicating a unknown/external
* error condition. When first called, this function will register the
* said error within the other Eina errors, together with a error
* message.
*/
inline Eina_Error unknown_error()
{
static Eina_Error error = eina_error_msg_static_register("Error from C++ from another value category error");
return error;
}
/**
* @brief Gets a <tt>std::generic_category</tt> instance as a <tt>eina::system_error_category</tt>.
* @return a <tt>std::generic_category</tt> instance as a <tt>eina::system_error_category</tt>.
*/
inline system_error_category const& get_generic_category()
{
return ::std::generic_category();
}
/**
* @brief Gets a <tt>std::system_category</tt> instance as a <tt>eina::system_error_category</tt>.
* @return <tt>std::system_category</tt> instance as a <tt>eina::system_error_category</tt>.
*/
inline system_error_category const& get_system_category()
{
return ::std::system_category();
}
/**
* @brief Typesafe representation of an @c Eina_Error.
*
* Used for improved compatibility with @e system_error library.
*/
enum error_type {};
/**
* @brief Specialized error category for Eina errors.
*/
struct error_category : system_error_category
{
/**
* @brief Name of the error category.
* @return String containing the word "eina"
*/
const char* name() const throw()
{
return "eina";
}
/**
* @brief Check if the given error code is equivalent to the given error condition.
* @param code Integer representing the error code.
* @param condition <tt>eina::error_condition</tt> object.
* @return @c true if @c code is equivalent to @c condition.
*/
bool equivalent(int code, eina::error_condition const& condition) const throw()
{
return code == condition.value();
}
/**
* @brief Check if the given error code is equivalent to the given error condition.
* @param code <tt>eina::error_code</tt> object.
* @param condition Integer representing the error condition.
* @return @c true if @c code is equivalent to @c condition.
*/
bool equivalent(eina::error_code const& code, int condition) const throw()
{
return code.value() == condition;
}
/**
* @brief Get the message related with the given error condition.
* @param condition Eina error condition.
* @return String containing the message related with the given error condition.
*
* This member function returns the error message related with the
* given error condition code.
*
* @note When the given condition code is not registered within the
* Eina errors it will return a string indicating that an error
* message is not available.
*/
std::string message(int condition) const
{
const char* e = ::eina_error_msg_get(condition);
@ -54,12 +135,29 @@ struct error_category : system_error_category
}
};
/**
* @brief Get a default <tt>eina::error_category</tt> object.
* @return Reference to a static instance of an <tt>eina::error_category</tt>.
*/
inline eina::system_error_category& eina_error_category()
{
static error_category _error_category;
return _error_category;
}
/**
* @brief Gets the error code for the last Eina error.
* @return <tt>eina::error_code</tt> for the last Eina error.
*
* This function gets the error code for the last Eina error and
* consumes it. The category of the returned <tt>eina::error_code</tt>
* is @c eina_error_category.
*
* @note If no errors have been occurred or if this functions have
* already been called after the last error occurrence a call to this
* function will return a default <tt>eina::error_code</tt> to indicates
* that there is no unconsumed error.
*/
inline eina::error_code get_error_code()
{
Eina_Error error = eina_error_get();
@ -72,6 +170,14 @@ inline eina::error_code get_error_code()
return eina::error_code();
}
/**
* @brief Sets an error code in the Eina library.
* @param e Error code. Should be an @c eina_error_category error.
*
* This function sets an error code in the Eina library. If the category
* of the given error code is not @c eina_error_category it will
* register an unknown error instead.
*/
inline void set_error_code(eina::error_code const& e)
{
if(e.category() == eina_error_category())
@ -80,6 +186,13 @@ inline void set_error_code(eina::error_code const& e)
eina_error_set(unknown_error());
}
/**
* @brief Gets the error condition for the last Eina error.
* @return <tt>eina::error_condition</tt> for the last Eina error.
*
* This function works exactly like @ref get_error_code but returns an
* <tt>eina::error_condition</tt> object instead.
*/
inline eina::error_condition get_error_condition()
{
Eina_Error error = eina_error_get();
@ -92,12 +205,35 @@ inline eina::error_condition get_error_condition()
return eina::error_condition();
}
/**
* @brief Gets the enum value of the last Eina error.
* @return Value of the last Eina error as an @c error_type.
*
* This function returns the error code for the last Eina error.
*
* Differently from @ref get_error_code and @ref get_error_condition,
* this function does not consume the last error.
*/
inline error_type get_error_code_enum()
{
return static_cast<error_type>( ::eina_error_get() );
}
/**
* @brief Throw an exception if there is a error set in Eina library.
* @throw <tt>eina::system_error</tt> containing the error identifier.
*
* This function is meant to be used after executing a operation that
* may set an Eina error. If an error code has been set this function
* will throw an exception.
*
* The thrown exception holds an <tt>eina::error_code</tt> equivalent to
* the one returned by @ref get_error_code.
*
* Like the @ref get_error_code function, this one consumes the last
* error code.
*/
inline void throw_on_error()
{
eina::error_code ec = get_error_code();
@ -107,13 +243,28 @@ inline void throw_on_error()
}
}
/**
* @}
*/
} }
/**
* @internal
* Template specialization for interoperability with the @e system_error
* standard library.
* @{
*/
namespace std {
template <> struct is_error_condition_enum< ::efl::eina::error_type> : true_type {};
template <> struct is_error_code_enum< ::efl::eina::error_type> : true_type {};
}
/**
* @}
*/
/**
* @}
*/
#endif

File diff suppressed because it is too large Load Diff

@ -10,8 +10,24 @@
#include <iterator>
#include <algorithm>
/**
* @addtogroup Eina_Cxx_Containers_Group
*
* @{
*/
namespace efl { namespace eina {
/**
* @defgroup Eina_Cxx_Inline_List_Group Inline List
* @ingroup Eina_Cxx_Containers_Group
*
* @{
*/
/**
* @internal
*/
template <typename T>
struct _inlist_node
{
@ -19,18 +35,27 @@ struct _inlist_node
T object;
};
/**
* @internal
*/
template <typename T>
_inlist_node<T>* _get_node(Eina_Inlist* l)
{
return static_cast<_inlist_node<T>*>(static_cast<void*>(l));
}
/**
* @internal
*/
template <typename T>
_inlist_node<T> const* _get_node(Eina_Inlist const* l)
{
return const_cast<Eina_Inlist*>(l);
}
/**
* @internal
*/
template <typename T>
Eina_Inlist* _get_list(_inlist_node<T>* n)
{
@ -40,38 +65,85 @@ Eina_Inlist* _get_list(_inlist_node<T>* n)
return 0;
}
/**
* @internal
*/
template <typename T>
Eina_Inlist const* _get_list(_inlist_node<T> const* n)
{
return _get_list(const_cast<_inlist_node<T>*>(n));
}
/**
* @internal
* Iterator for Inline List
*/
template <typename T>
struct _inlist_iterator
{
typedef typename std::remove_const<T>::type value_type;
typedef value_type* pointer;
typedef value_type& reference;
typedef std::ptrdiff_t difference_type;
typedef std::bidirectional_iterator_tag iterator_category;
typedef typename std::remove_const<T>::type value_type; /**< Type for the list elements. */
typedef value_type* pointer; /**< Type for a pointer to an element. */
typedef value_type& reference; /**< Type for a reference to an element. */
typedef std::ptrdiff_t difference_type; /**< Type to represent the distance between two iterators. */
typedef std::bidirectional_iterator_tag iterator_category; /**< Defines the iterator as being a bidirectional iterator. */
/**
* @brief Default constructor. Creates an uninitialized iterator.
*/
_inlist_iterator() {}
/**
* @brief Creates an iterator from a inline list and a node.
* @param list Pointer to the inline list.
* @param node Pointer to the node.
*/
explicit _inlist_iterator(_inlist_node<value_type>* list, _inlist_node<value_type>* node)
: _list(list), _node(node) {}
/**
* @brief Copy constructor. Creates a copy of the given iterator.
* @param other Other iterator.
*/
_inlist_iterator(_inlist_iterator<typename std::remove_const<T>::type> const& other)
: _list(other._list), _node(other._node) {}
/**
* @brief Move the iterator to the next position in the list.
* @return The iterator itself.
*
* This operator increments the iterator, making it point to the
* position right after the current one.
* At the end, it returns a reference to itself.
*/
_inlist_iterator<T>& operator++()
{
_node = _get_node<value_type>(_node->__in_list.next);
return *this;
}
/**
* @brief Move the iterator to the next position in the list.
* @return Copy of the iterator before the increment.
*
* This operator increments the iterator, making it point to the next
* position right after the current one.
* At the end, it returns a copy of the iterator before the increment.
*/
_inlist_iterator<T> operator++(int)
{
_inlist_iterator<T> tmp(*this);
++*this;
return tmp;
}
/**
* @brief Move the iterator to the previous position in the list.
* @return The iterator itself.
*
* This operator decrements the iterator, making it point to the
* position right before the current one.
* At the end, it returns a reference to itself.
*/
_inlist_iterator<T>& operator--()
{
if(_node)
@ -80,32 +152,65 @@ struct _inlist_iterator
_node = _get_node<value_type>(_list->__in_list.last);
return *this;
}
/**
* @brief Move the iterator to the previous position in the list.
* @return Copy of the iterator before the decrement.
*
* This operator decrements the iterator, making it point to the
* position right before the current one.
* At the end, it returns a copy of the iterator before the decrement.
*/
_inlist_iterator<T> operator--(int)
{
_inlist_iterator<T> tmp(*this);
--*this;
return tmp;
}
/**
* @brief Get a reference to the element currently pointed by the iterator.
* @return Reference to the current element.
*/
T& operator*() const
{
return _node->object;
}
/**
* @brief Return a pointer to the current element, which member will be accessed.
* @return Pointer to the element currently pointed by the iterator.
*/
T* operator->() const
{
return &_node->object;
}
/**
* @internal
*/
_inlist_node<value_type>* native_handle()
{
return _node;
}
/**
* @internal
*/
_inlist_node<value_type> const* native_handle() const
{
return _node;
}
private:
_inlist_node<value_type>* _list;
_inlist_node<value_type>* _node;
_inlist_node<value_type>* _list; /**< Handle to the original list. */
_inlist_node<value_type>* _node; /**< Handle to the current node. */
/**
* @brief Check if both iterators are pointing to the same node.
* @param lhs First iterator to be compared.
* @param rhs Second iterator to be compared.
* @return @c true if both iterators are pointing to the same node, @c false otherwise.
*/
template <typename U>
friend struct _inlist_iterator;
friend bool operator==(_inlist_iterator<T> lhs, _inlist_iterator<T> rhs)
@ -114,12 +219,21 @@ private:
}
};
/**
* @brief Check if iterators are not pointing to the same node.
* @param lhs First iterator to be compared.
* @param rhs Second iterator to be compared.
* @return @c true if iterators are not pointing to the same node, @c false otherwise.
*/
template <typename T>
bool operator!=(_inlist_iterator<T> lhs, _inlist_iterator<T> rhs)
{
return !(lhs == rhs);
}
/**
* @internal
*/
struct _inlist_access_traits {
template <typename T>
struct const_iterator
@ -242,49 +356,93 @@ struct _inlist_access_traits {
template <typename T, typename Allocator>
class inlist;
/**
* @ingroup Eina_Cxx_Range_Group
*
* Range for inline list elements.
*/
template <typename T>
struct range_inlist : _range_template<T, _inlist_access_traits>
{
typedef _range_template<T, _inlist_access_traits> _base_type;
typedef typename _base_type::value_type value_type;
typedef typename _base_type::native_handle_type native_handle_type;
typedef _range_template<T, _inlist_access_traits> _base_type; /**< Type for the base class. */
typedef typename _base_type::value_type value_type; /**< The type of each element. */
typedef typename _base_type::native_handle_type native_handle_type; /** Type for the native Eina inline list handle. */
/**
* @brief Creates a range from a native Eina inline list handle.
*/
range_inlist(native_handle_type list)
: _base_type(list) {}
/**
* @brief Creates a range from a inline list object.
*/
template <typename Allocator>
range_inlist(inlist<value_type, Allocator>& list)
: _base_type(list.native_handle())
{}
};
/**
* @brief Check the given ranges are equal to each other.
* @param lhs Range object at the left side of the expression.
* @param rhs Range object at the right side of the expression.
* @return @c true if the ranges are equal, @c false otherwise.
*
* This operator checks if the given ranges are equal to each other. To
* be considered equal both ranges need to have the same size, and each
* element in one range must be equal to the element at the same
* position in the other.
*/
template <typename T>
bool operator==(range_inlist<T>const& lhs, range_inlist<T>const& rhs)
{
return lhs.size() == rhs.size() && std::equal(lhs.begin(), lhs.end(), rhs.begin());
}
/**
* @brief Returns the opposite of @ref operator==(range_inlist<T>const& lhs, range_inlist<T>const& rhs).
*/
template <typename U>
bool operator!=(range_inlist<U> const& lhs, range_inlist<U>const& rhs)
{
return !(lhs == rhs);
}
/**
* Common implementations for inline list.
*/
template <typename T, typename Allocator>
struct _inlist_common_base
{
typedef typename Allocator::template rebind<_inlist_node<T> >::other node_allocator_type;
typedef Allocator allocator_type;
typedef _inlist_node<T> node_type;
typedef typename Allocator::template rebind<_inlist_node<T> >::other node_allocator_type; /**< Type for the allocator of the node. */
typedef Allocator allocator_type; /**< Type for the allocator. */
typedef _inlist_node<T> node_type; /**< Type for the list node. */
/**
* @brief Creates a list with the given allocator.
* @param allocator Allocator object.
*/
_inlist_common_base(Allocator allocator)
: _impl(allocator) {}
/**
* @brief Creates an empty inline list.
*/
_inlist_common_base()
{}
/**
* @brief Destructor. Deallocate all nodes of the list.
*/
~_inlist_common_base()
{
clear();
}
/**
* @brief Deallocate all nodes of the list.
*/
void clear()
{
Eina_Inlist* p = _impl._list;
@ -301,11 +459,18 @@ struct _inlist_common_base
}
_impl._list = 0;
}
/**
* @brief Get the allocator used by the list.
*/
node_allocator_type& get_node_allocator()
{
return _impl;
}
/**
* @internal
*/
// For EBO
struct _inlist_impl : node_allocator_type
{
@ -317,40 +482,77 @@ struct _inlist_common_base
Eina_Inlist* _list;
};
_inlist_impl _impl;
_inlist_impl _impl; /**< @internal */
private:
/** Disabled copy constructor. */
_inlist_common_base(_inlist_common_base const& other);
/** Disabled assignment operator. */
_inlist_common_base& operator=(_inlist_common_base const& other);
};
/**
* C++ wrapper for the native Eina inline list.
*
* It provides an OOP interface to the @c Eina_Inlist functions, and
* automatically take care of allocating and deallocating resources using
* the RAII programming idiom.
*
* It also provides additional member functions to facilitate the access
* to the list content, much like a STL list.
*/
template <typename T, typename Allocator = std::allocator<T> >
class inlist : protected _inlist_common_base<T, Allocator>
{
typedef _inlist_common_base<T, Allocator> _base_type;
typedef typename _base_type::node_type _node_type;
typedef _inlist_common_base<T, Allocator> _base_type; /**< Type for the base class. */
typedef typename _base_type::node_type _node_type; /**< Type for each node */
public:
typedef typename _base_type::allocator_type allocator_type;
typedef typename allocator_type::value_type value_type;
typedef typename allocator_type::reference reference;
typedef typename allocator_type::const_reference const_reference;
typedef _inlist_iterator<T con