picontainers.h doxygen partial

2022-03-14 17:14:29 +03:00
parent 99061f6e24
commit 99280a40ef
3 changed files with 120 additions and 65 deletions
--- a/doc/examples/picontainers.cpp
+++ b/doc/examples/picontainers.cpp
@@ -4,14 +4,17 @@ void _() {
 //! [foreach]
 PIVector<int> vec;
 vec << 1 << 2 << 3;
-piForeach (int & i, vec)
-	cout << i << ", ";
-// 1, 2, 3, 
-piForeach (int & i, vec)
-	i++;
-piForeach (int & i, vec)
-	cout << i << ", ";
-// 2, 3, 4, 
+
+piForeach (int & i, vec) piCout << i;
+// 1
+// 2
+// 3
+
+piForeach (int & i, vec) i++;
+piForeach (int & i, vec) piCout << i;
+// 2
+// 3
+// 4
 //! [foreach]
 //! [foreachC]
 PIVector<int> vec;
--- a/libs/main/containers/picontainers.h
+++ b/libs/main/containers/picontainers.h
@@ -1,12 +1,19 @@
-/*! @file picontainers.h
- * @brief Base for generic containers
+/*! \file picontainers.h
+ * \brief
+ * \~english Base macros for generic containers
+ * \~russian Базовые макросы для контейнеров
 *
- * This file declare all containers and useful macros
- * to use them
+ * \authors
+ * \~english
+ * Ivan Pelipenko peri4ko@yandex.ru;
+ * Andrey Bychkov work.a.b@yandex.ru;
+ * \~russian
+ * Иван Пелипенко peri4ko@yandex.ru;
+ * Андрей Бычков work.a.b@yandex.ru;
 */
 /*
 	PIP - Platform Independent Primitives
-	Base for generic containers
+	Base macros for generic containers
 	Ivan Pelipenko peri4ko@yandex.ru

 	This program is free software: you can redistribute it and/or modify
@@ -37,26 +44,9 @@
 #include <type_traits>
 #include <string.h>
 #include <new>
-#ifndef PIP_MEMALIGN_BYTES
-#  define PIP_MEMALIGN_BYTES (sizeof(void*)*4)
-#endif
-#ifdef WINDOWS
-#  ifdef CC_GCC
-#    define amalloc(s) __mingw_aligned_malloc(s, PIP_MEMALIGN_BYTES)
-#    define afree(p) __mingw_aligned_free(p)
-#  else
-#    ifdef CC_VC
-#      define amalloc(s) _aligned_malloc(s, PIP_MEMALIGN_BYTES)
-#      define afree(p) _aligned_free(p)
-#    endif
-#  endif
-#else
-#  define amalloc(s) aligned_alloc(PIP_MEMALIGN_BYTES, s)
-#  define afree(p) free(p)
-#endif


-#ifdef DOXYGEN
+#if 0

 /*!@brief Macro for iterate any container
 * \details Use this macros instead of standard "for"
@@ -94,26 +84,64 @@


 template <typename C>
-struct _reverse_wrapper {
-	C & c_;
-	_reverse_wrapper(C & c): c_(c) {}
-	_reverse_wrapper(const C & c): c_(const_cast<C&>(c)) {}
+class _PIReverseWrapper {
+public:
+	_PIReverseWrapper(C & c): c_(c) {}
+	_PIReverseWrapper(const C & c): c_(const_cast<C&>(c)) {}
 	typename C::reverse_iterator begin() {return c_.rbegin();}
 	typename C::reverse_iterator end() {return c_.rend(); }
 	typename C::const_reverse_iterator begin() const {return c_.rbegin();}
 	typename C::const_reverse_iterator end() const {return c_.rend(); }
+private:
+	C & c_;
 };

-template <typename C> _reverse_wrapper<C> _reverse_wrap(C & c) {return _reverse_wrapper<C>(c);}
-template <typename C> _reverse_wrapper<C> _reverse_wrap(const C & c) {return _reverse_wrapper<C>(c);}
+template <typename C> _PIReverseWrapper<C> PIReverseWrap(C & c) {return _PIReverseWrapper<C>(c);}
+template <typename C> _PIReverseWrapper<C> PIReverseWrap(const C & c) {return _PIReverseWrapper<C>(c);}


-#  define piForTimes(c) for(int _i##c = 0; _i##c < c; ++_i##c)
+/*! \brief
+ * \~english Macro for short replacement of standart "for"
+ * \~russian Макрос для короткой записи стандартного цикла "for"
+ * \param c
+ * \~english Iteration times in loop
+ * \~russian Количество итераций цикла
+ */
+#define piForTimes(c) for(int _i##c = 0; _i##c < c; ++_i##c)

-#  define piForeach(i,c) for(i : c)
-#  define piForeachC(i,c) for(const i : c)
-#  define piForeachR(i,c) for(i : _reverse_wrap(c))
-#  define piForeachRC(i,c) for(const i : _reverse_wrap(c))
+
+/*! \brief
+ * \~english Macro for iterate any container
+ * \~russian Макрос для перебора любых контейнеров
+ * \deprecated
+ * \~english Deprecated, using only for backward compatibility. Use "c++ range for".
+ * \~russian Устарело, используется только для обратной совместимости. Используйте "c++ range for".
+ * \details
+ * \~english Get read/write access to each element of container.
+ * Iterating in forward direction.
+ * Example of using:
+ * \~russian Перебор всех элементов контейнера с доступом на чтение и запись.
+ * Перебор осуществляется в прямом порядке.
+ * Пример использования:
+ * \code
+ * PIVector<int> vec;
+ * vec << 1 << 2 << 3;
+ * piForeach(int & i, vec) piCout << i;
+ * // 1
+ * // 2
+ * // 3
+ * piForeach(int & i, vec) i++;
+ * piForeach(int & i, vec) piCout << i;
+ * // 2
+ * // 3
+ * // 4
+ * \endcode
+ */
+#define piForeach(i, c) for(i : c)
+
+#define piForeachC(i, c) for(const i : c)
+#define piForeachR(i, c) for(i : PIReverseWrap(c))
+#define piForeachRC(i, c) for(const i : PIReverseWrap(c))

 #  define piForeachCR piForeachRC

--- a/libs/main/core/pibase.h
+++ b/libs/main/core/pibase.h
@@ -1,4 +1,4 @@
-/*! @file pibase.h
+/*! \file pibase.h
 * \brief
 * \~english Base types and functions
 * \~russian Базовые типы и методы
@@ -83,40 +83,45 @@
 #  define PIP_DEBUG

 //! \brief
-//! \~english Macro is defined when host is any Windows
-//! \~russian Макрос объявлен когда система Windows
+//! \~english Macro is defined when operation system is any Windows
+//! \~russian Макрос объявлен когда операционная система Windows
 #  define WINDOWS

 //! \brief
-//! \~english Macro is defined when host is QNX or Blackberry
-//! \~russian Макрос объявлен когда система QNX или Blackberry
+//! \~english Macro is defined when operation system is QNX or Blackberry
+//! \~russian Макрос объявлен когда операционная система QNX или Blackberry
 #  define QNX

 //! \brief
-//! \~english Macro is defined when host is Blackberry
-//! \~russian Макрос объявлен когда система Blackberry
+//! \~english Macro is defined when operation system is Blackberry
+//! \~russian Макрос объявлен когда операционная система Blackberry
 #  define BLACKBERRY

 //! \brief
-//! \~english Macro is defined when host is FreeBSD
-//! \~russian Макрос объявлен когда система FreeBSD
+//! \~english Macro is defined when operation system is FreeBSD
+//! \~russian Макрос объявлен когда операционная система FreeBSD
 #  define FREE_BSD

 //! \brief
-//! \~english Macro is defined when host is Mac OS
-//! \~russian Макрос объявлен когда система Mac OS
+//! \~english Macro is defined when operation system is Mac OS
+//! \~russian Макрос объявлен когда операционная система Mac OS
 #  define MAC_OS

 //! \brief
-//! \~english Macro is defined when host is Android
-//! \~russian Макрос объявлен когда система Android
+//! \~english Macro is defined when operation system is Android
+//! \~russian Макрос объявлен когда операционная система Android
 #  define ANDROID

 //! \brief
-//! \~english Macro is defined when host is any Linux
-//! \~russian Макрос объявлен когда система Linux
+//! \~english Macro is defined when operation system is any Linux
+//! \~russian Макрос объявлен когда операционная система Linux
 #  define LINUX

+//! \brief
+//! \~english Macro is defined when operation system is FreeRTOS
+//! \~russian Макрос объявлен когда операционная система FreeRTOS
+#  define FREERTOS
+
 //! \brief
 //! \~english Macro is defined when compiler is GCC or MinGW
 //! \~russian Макрос объявлен когда компилятор GCC или MinGW
@@ -127,19 +132,29 @@
 //! \~russian Макрос объявлен когда PIP решил что система поддерживает локализацию
 #  define HAS_LOCALE

+//! \brief
+//! \~english Macro is defined when PIP is building for embedded systems
+//! \~russian Макрос объявлен когда PIP собирается для встраиваемых систем
+#  define MICRO_PIP
+
 //! \brief
 //! \~english Macro is defined when compiler is Visual Studio
 //! \~russian Макрос объявлен когда компилятор Visual Studio
 #  define CC_VC

+//! \brief
+//! \~english Macro is defined when compiler is AVR GCC
+//! \~russian Макрос объявлен когда компилятор AVR GCC
+#  define CC_AVR_GCC
+
 //! \brief
 //! \~english Macro is defined when compiler is unknown
 //! \~russian Макрос объявлен когда компилятор неизвестен
 #  define CC_OTHER

 //! \brief
-//! \~english Macro is defined when PIP can use "rt" library for "PITimer::ThreadRT" timers implementation
-//! \~russian Макрос объявлен когда PIP может использовать библиотеку "rt" для "PITimer::ThreadRT" реализации таймера
+//! \~english Macro is defined when PIP can use "rt" library for \a PITimer::ThreadRT timers implementation
+//! \~russian Макрос объявлен когда PIP может использовать библиотеку "rt" для \a PITimer::ThreadRT реализации таймера
 #  define PIP_TIMER_RT

 //! \brief
@@ -177,7 +192,8 @@
 //! \~russian Макрос для окончания статической инициализации
 #  define STATIC_INITIALIZER_END

-
+#undef MICRO_PIP
+#undef FREERTOS
 #endif //DOXYGEN

 #ifdef CC_AVR_GCC
@@ -343,10 +359,18 @@
 } _PIP_ADD_COUNTER(_pip_initializer_);


-#ifdef MICRO_PIP
-#  define PIP_MIN_MSLEEP 10.
-#else
+//! \brief
+//! \~english Minimal sleep in milliseconds for internal PIP using
+//! \~russian Минимальное значание задержки в милисекундах для внутреннего использования в библиотеке PIP
+//! \details
+//! \~english Using in \a piMinSleep(), \a PIThread, \a PITimer::Pool. By default 1ms.
+//! \~russian Используется в \a piMinSleep(), \a PIThread, \a PITimer::Pool. По умолчанию равна 1мс.
+#ifndef PIP_MIN_MSLEEP
+#  ifndef MICRO_PIP
 #    define PIP_MIN_MSLEEP 1.
+#  else
+#    define PIP_MIN_MSLEEP 10.
+#  endif
 #endif