Version 10.9.10

ManWork/LaTex/develop.tex

@@ -828,6 +828,109 @@ \subsubsection{SETMIN}
 	\item[PTRCHRC\_(p)] Преобразует указатель p к типу (const char *) используя reinterpret\_cast<>
 \end{description}
 
+\section{Универсальные семантические правила}
+
+\subsection{Member function Z()}
+Функция Z() инициализирует состояние экземпляра класса или
+структуры. Эта функция не обязана и, чаще всего, не должна освобождать память, выделенную
+под внутренние элементы класса если эта память может быть использована при дальнейшей
+работе с экземпляром.
+
+Функция должна вернуть ссылку на экземпляр this.
+
+Пример:
+\begin{lstlisting}
+	class ABC {
+	public:
+		ABC() : A(0), P_Buf(0), UsedBufSize(0), AllocatedBufSize(0)
+		{
+		}
+		~ABC()
+		{
+			// Деструктор, в отличии, от Z() освобождает память,
+			// выделенную под P_Buf, но не трогает "плоские" переменные,
+			// поскольку экземпляр объекта прекращает существование.
+			SAlloc::F(P_Buf);
+		}
+		ABC & Z()
+		{
+			// Мы вернули состояние переменной A в исходное состояние.
+			// Обнулили используемый размер буфера P_Buf, но 
+			// не стали освобождать память, выделенную под 
+			// этот буфер и менять AllocatedBufSize дабы
+			// при последующем использовании не распределять память вновь.
+			A = 0;
+			UsedBufSize = 0;
+			return *this;
+		}
+	private:
+		long   A;
+		void * P_Buf;
+		size_t UsedBufSize;
+		size_t AllocatedBufSize;
+	}
+\end{lstlisting}
+
+\subsection{Member function IsEqual()}
+Функция-член IsEqual() сравнивает экземпляр this некоторого объекта с экземпляром, переданным
+единственным аргументом функции. Чаще всего типом этого аргумента является тот же класс, которому
+принадлежит функция. Но это - не жесткое правило: могут быть и иные реализации IsEqual, принимающие
+в качестве аргумента какие-либо иные типы.
+
+Аргумент функции в общем случае следует передавать по const-ссылке.
+
+Функция возвращает значение типа int. Если this равен аргументу, то возвращается !0 (любое ненулевое значение: 
+желательно единица, однако допустимы вариации). Если this не равен аргументу, то возвращает 0.
+
+Функция всегда имеет квалификатор const, равно как и аргумент, передаваемый ей так же имеет квалификатор const. То есть
+функция не меняет состояние this, равно как и состояние объекта, ссылка на который передана ей для сравнения.
+Вероятно, исключения из этого правила могут существовать, но в таком случае это необходимо объяснить в комментариях.
+
+Общее правило для формата вызова функций этого семейства FASTCALL. Правило не обязательное, но учитывая то,
+что функция имеет единственный аргумент, применение FASTCALL в этом случае весьма эффективно (большинство
+компиляторов, обрабатывающих FASTCALL, ничего на стеке передавать не будут - только в регистрах).
+
+Пример (продолжим примеры с выдуманным классом ABC):
+\begin{lstlisting}
+	class ABC {
+	public:
+		ABC() : A(0), P_Buf(0), UsedBufSize(0), AllocatedBufSize(0)
+		{
+		}
+		~ABC()
+		{
+			SAlloc::F(P_Buf);
+		}
+		int   FASTCALL IsEqual(const ABC & rS) const
+		{
+			int    eq = 1;
+			// Попутно проверим очевидные инварианты класса
+			assert(UsedBufSize <= AllocatedBufSize);
+			assert(rS.UsedBufSize <= rS.AllocatedBufSize);
+			assert(!UsedBufSize || P_Buf);
+			assert(!rS.UsedBufSize || rS.P_Buf);
+			if(A != rS.A)			
+			eq = 0;
+			else if(UsedBufSize != rS.UsedBufSize)
+			eq = 0;
+			else if(UsedBufSize && memcmp(P_Buf, rS.P_Buf, UsedBufSize) != 0) 
+			eq = 0;
+			return eq;
+		}
+		ABC & Z()
+		{
+			A = 0;
+			UsedBufSize = 0;
+			return *this;
+		}
+	private:
+		long   A;
+		void * P_Buf;
+		size_t UsedBufSize;
+		size_t AllocatedBufSize;
+	}
+\end{lstlisting}
+
 \chapter{Общие функции}
 
 В этой главе обсуждаются общеупотребимые функции и методы, а именно:
@@ -875,6 +978,18 @@ \subsubsection{SETMIN}
 	аллокатору памяти с целью реализации высокооптимизированного аллокатора. 
 \end{enumerate}
 
+\subsection{Проверка на null освобождаемой памяти}
+Специальное замечание относительно освобождения памяти функциями free(), SAlloc::F()
+и оператором delete: стандарты c/c++ гарантируют, что эти функции игнорируют нулевые
+указатели. Поэтому не следует проверять на null указатели перед вызовом этих и родственных
+функций - не надо загромождать и без того гигантский код.
+
+Единственное исключение из вышеприведенного правила:  если вы абсолютно уверены, что
+участок кода, где осуществляется освобождение распределенной памяти, критичен по 
+быстродействию (очень часто вызывается, например, в циклах и т.д.) то проверка
+на null перед вызовом функции (оператора) освобождения памяти поможет сэкономить "пару тактов"
+процессора. Пометьте такую проверку комментарием // $@$speedcritical чтобы как-то оправдаться.
+
 \section{Манипуляции с участками памяти}
 
 Функции memcpy, memmove, memset, memcmp опеределены в slib.h как макросы, для использования реализации из библиотеки 
@@ -988,7 +1103,7 @@ \subsubsection{SETMIN}
 	\item При передаче ей нулевого указателя вызывает системное исключение (не проверяет аргумент
 	на ноль).
 	\item При компиляции c++ принимает только параметр типа const char * (но отказывается работать
-	с const unsignec char * без преобразования типов). 
+	с const unsigned char * без преобразования типов). 
 	\item Для unicode-символов требуется отдельная функция wcslen
 \end{itemize}