PIByteArray doc

libs/main/core/pibytearray.cpp

@@ -21,6 +21,82 @@
 #include "pistringlist.h"
 #include <iostream>
 
+//! \class PIByteArray
+//!
+//! \~\brief
+//! \~english The PIByteArray class provides an array of bytes
+//! \~russian Класс PIByteArray представляет собой массив байтов
+//!
+//! \~\details
+//! \~english
+//! %PIByteArray used to store raw bytes.
+//! It can be constructed from any data and size.
+//! You can use %PIByteArray as binary stream
+//! to serialize/deserialize any objects and data.
+//! This class based on PIDeque<uchar> and provide some handle function
+//! to manipulate it.
+//! \~russian
+//! %PIByteArray используется для хранения байтов.
+//! Он может быть сконструирован из любых даных.
+//! Можно использовать %PIByteArray как потоковый объект
+//! для сериализации/десериализации любых типов и данных.
+//! Этот класс наследован от PIDeque<uchar> и предоставляет набор
+//! удобных методов для работы с байтами.
+//!
+//! \~english \section PIByteArray_sec0 Usage
+//! \~russian \section PIByteArray_sec0 Использование
+//! \~english
+//! %PIByteArray can be used to store custom data and manipulate it. There are many
+//! stream operators to store/restore common types to byte array. Store operators
+//! places data at the end of array, restore operators takes data from the beginning
+//! of array.
+//! In addition there are Hex and Base64 convertions
+//! \~russian
+//! %PIByteArray может быть использован для сохранения любых данных и работы с ними.
+//! Он предоставляет множество операторов для сохранения/извлечения общих типов.
+//! Операторы сохранения добавляют данные в конец массива, а операторы извлечения
+//! берут данные из его начала.
+//!
+//! \~english
+//! One of the major usage of %PIByteArray is stream functions. You can form binary
+//! packet from many types (also dynamic types, e.g. PIVector) with one line:
+//! \~russian
+//! Один из основных сценариев использования  %PIByteArray - это потоковый объект.
+//! Можно сформировать пакет бинарных данных из многих типов (также и контейнеров,
+//! например, PIVector) в одну строку:
+//! \~\snippet pibytearray.cpp 0
+//!
+//! \~english
+//! Or you can descibe stream operator of your own type and store/restore vectors of
+//! your type:
+//! \~russian
+//! Также можно описать операторы сохранения/извлечения для собственных типов:
+//! \~\snippet pibytearray.cpp 1
+//!
+//! \~english
+//! For store/restore custom data blocks there is PIByteArray::RawData class. Stream
+//! operators of this class simply store/restore data block to/from byte array:
+//! \~russian
+//! Для сохранения/извлечения блоков произвольных данных используется класс PIByteArray::RawData.
+//! Потоковые операторы для него просто сохраняют/извлекают блоки байтов:
+//! \~\snippet pibytearray.cpp 2
+//!
+//! \~english \section PIByteArray_sec1 Attention
+//! \~russian \section PIByteArray_sec1 Внимание
+//! \~english
+//! Stream operator of %PIByteArray store byte array as vector, not simply append
+//! content of byte array. This operators useful to transmit custom data as %PIByteArray
+//! packed into parent byte array, e.g. to form packet from %PIByteArray.
+//! To append one byte array to another use funtion \a append().
+//! \~russian
+//! Потоковый оператор для типа %PIByteArray сохраняет его как контейнер,
+//! а не просто добавляет его содержимое в конец. Этот оператор полезен для управляемой
+//! упаковки произвольных данных в виде %PIByteArray.
+//! Для добавления содержимого одного байтового массива к другому используется
+//! метов \a append().
+//! \~\snippet pibytearray.cpp 3
+//!
+
 
 static const uchar base64Table[64] = {
 0x41, 0x42, 0x43, 0x44, 0x45, 0x46, 0x47, 0x48,
@@ -221,6 +297,19 @@ PIByteArray & PIByteArray::decompressRLE(uchar threshold) {
 }
 
 
+//! \~\details
+//! \~english
+//! This is simple sum of all bytes, if "inverse" then add 1 and inverse.
+//! Pseudocode:
+//! \~russian
+//! Это простая сумма всех байтов, если "inverse", то ещё добавляется 1 и инвертируется результат.
+//! Псевдокод:
+//! \~\code
+//! for (i)
+//!		sum += at(i);
+//! if (inverse) return ~(sum + 1);
+//! else return sum;
+//! \endcode
 uchar PIByteArray::checksumPlain8(bool inverse) const {
 	uchar c = 0;
 	int sz = size_s();
@@ -231,6 +320,19 @@ uchar PIByteArray::checksumPlain8(bool inverse) const {
 }
 
 
+//! \~\details
+//! \~english
+//! This is sum of all bytes multiplied by index+1, if inverse then add 1 and inverse.
+//! Pseudocode:
+//! \~russian
+//! Это простая сумма всех байтов, умноженных на индекс+1, если "inverse", то ещё добавляется 1 и инвертируется результат.
+//! Псевдокод:
+//! \~\code
+//! for (i)
+//!		sum += at(i) * (i + 1);
+//! if (inverse) return ~(sum + 1);
+//! else return sum;
+//! \endcode
 uint PIByteArray::checksumPlain32(bool inverse) const {
 	uint c = 0;
 	int sz = size_s();