~vbursian/research-assistant/intervers

////////////////////////////////////////////////////////////////////////////////
/*! @file PhysValue.cpp   Физвеличина.
- Part of RANet - Research Assistant Net Library (based on ANSI C++).
- Copyright(C) 2010, Viktor E. Bursian, St.Petersburg, Russia.
                     Viktor.Bursian@mail.ioffe.ru
*///////////////////////////////////////////////////////////////////////////////
#include "PhysValue.h"
#include "Symbols.h"
#include "Log.h"
namespace RA {
//------------------------------------------------------------------------------

///*! Максимальное число знаков, выводимых при нулевой погрешности */
//unsigned short int            sPhysValue::MaxDigits = 7;

/*! Уровень нормализации, выполняемой после каждой операции */
unsigned short int            sPhysValue::DraftNormalization = 1;

/*! Уровень нормализации, выполняемой перед выводом (в sPhysValue::Text) */
unsigned short int            sPhysValue::BriefNormalization = 4;

/*! Уровень нормализации, выполняемой перед редактированием пользователем */
unsigned short int            sPhysValue::SmartNormalization = 5;

//--------------------------------------------------------------- sPhysValue ---
/*! @class sPhysValue

@par "Важное замечание о побудительных причинах"

Как бы странно это ни звучало, основная причина введения в программу физвеличин
обусловлена желанием, во-первых, <b>показывать численные значения и шкалы
графиков в удобоваримом для человеческого восприятия виде</b>, и во-вторых,
предложить для этого такой алгоритм, который не зависел бы от особенностей
конкретной прикладной сферы применения.

То есть информация о числе знаков, осмысленных при выводе на экран, о
множителе, приводящем число, измеренное в каких-нибудь квантах АЦП, к
осмысленным единицам, и об этих самых единицах, которые надо "нарисовать" рядом
со значением, должна содержаться в самом "числе", а не во всех тех
многочисленных местах ядра программы, где требуется вывести число на экран или
ввести его из редактируемого пользователем поля.

Оказывается, что для этого не нужно изобретать новых типично "программистских"
трюков.  Общепринятое понятие физвеличины потенциально содержит в себе решение
проблемы.

И уже в качестве дополнительных, но крайне приятных бонусов, на этом пути можно
получить лучшую читаемость и лаконичность программы для программиста,
унификацию межмодульного интерфейса для команды программистов, и целый
ряд новых возможностей для пользователя.

@par "Область значений"

Как и тип RA::real поддерживает расширенное понятие числа с плавающей точкой,
включающее плюс бесконечность (RA::real_inf), минус бесконечность
(-RA::real_inf) и неопределённость (RA::real_nan).

Количество знаков в мантиссе такое же, как у real, а диапазон изменения порядка
расширен до неприличия.  Последнее получилось из-за нормализации, при которой
мантисса держится вблизи единицы плюс-минус несколько порядков, а оставшаяся
часть порядка хранится в отдельном члене вида int.

@par "Погрешность физвеличин"

Погрешность используется прежде всего при выводе физвеличины. Вывод может
осуществляться в полной форме - @a значение ± @a погрешность, но чаще в краткой -
без погрешности (см. параметр @a detalization в sPhysValue::Text(...) и
параметр @a error_is_visible в конструкторе sPhysValueField). Однако в обоих
случаях число выводимых знаков зависит от погрешности.

Вводятся числа, как правило, также в краткой форме - без явного указания
погрешности.  Однако погрешность автоматически присваивается, исходя из
количества введённых знаков.  Таким образом, число, введённое как "36.6", так и
будет потом выводиться, а не превратится в монструозное
"3.65999999999999998e+001".  С другой стороны, от пользователя ожидается
б<i>о</i>льшая ответственность в обращении с нулями на конце представления
чисел. В отличие от математики, в физике и в RA они все значащие!  Так, среди
трёх величин "0.3V", "300mV" и "0.300V" первые две @b разные (отличаются
погрешностью), а последние две идентичны.

Внутри программы погрешность либо прямо задаётся в конструкторе, либо получается
в результате операций над физвеличинами.  В последнем случае применён алгоритм
лишь немногим умнее "школьного".  Так, для погрешности произведения:
@code
      ∆(x*y) = |x*∆y| + |∆x*y| + ∆x*∆y
@endcode
где последний член существенен, когда относительная погрешность одного из
сомножителей больше или порядка единицы.

Такие простые правила позволяют разумно оценить погрешность в простых,
однократно исполняемых вычислениях, но легко приводят к куммулятивной потере
точности при неаккуратном вычислении чего-нибудь в цикле (хотя <b>собственно
значения всегда вычисляются с максимальной для типа RA::real точностью, и лишние
с точки зрения погрешности знаки никогда не отбрасываются</b>).  Не говоря уж
о дополнительных затратах процессорного времени.  Ещё раз подчеркну: физвеличины
введены не для внутренней кухни отдельных частей программы, а для унификации
обмена между пользователем и программой, а также между частями программы,
написанными в разное время и, возможно, разными программистами.

@par "Единицы измерения физвеличин"

Про базовые, производные и составные единицы, а также про систему единиц
следует прочитать в документации к классам sUnit и sUnits.  Здесь обсуждаются
лишь новые нюансы их использования в физвеличинах.

@par "Единицы измерения физвеличин-переменных и физвеличин-членов класса"

Такие объекты обычно имеют конкретный физический смысл и, следовательно,
размерность.  Имеется возможность зафиксировать их единицы при инициализации.
При этом вид sPhysValue как бы сужается (динамически) до понятия "физвеличина
указанной размерности", то есть такой переменной нельзя будет присвоить
выражение в несопоставимых единицах.  Читайте описания конструкторов и примеры
в них.

@note Внимание! При отсутствии явной инициализации С++ использует конструктор
sPhysValue::sPhysValue(), что порождает переменную или член с нефиксированными
единицами.

@par "Константы в тексте"
@code
сsPhysValue  pi(3.141593,0.0000005); //адекватное определение числа пи

... time / sPhysValue("ms")  ... //переменная time делится на одну (1!)
                                 //миллисекунду

sPhysValue    A("m*s-2");
A = sPhysValue(100,"km/hour") / sPhysValue(11.3,0.1,"s");
std::cout << A.Text(); //выводит максимальное ускорение моей Меривы в СИ
@endcode

@par "Единицы в процессе вычислений и при присваивании"

Выражение из предыдущего примера будет иметь правильные, но странные единицы:
hour<sup>-1</sup>*km*s<sup>-1</sup>.

При присваивании выражение в правой части приводится к единицам, заданным для
переменной-получателя.  Это можно и нужно использовать для перевода в желаемые
единицы.

@par "Нормализация"

Перед выводом для пользователя физвеличина нормализуется так, чтобы все нули в
текстовом представлении были значащими с учётом её погрешности.  Например,
величину "300 ± 15 mV" нельзя показывать в краткой форме как "300 mV",
адекватное представление будет "0.30 V".

Кроме этого, нормализация старается
- добиться, чтобы порядок в десятичном множителе был кратен трём;
- по возможности "растворить" порядок в метрических префиксах единиц;
- сделать единицы удобочитаемыми (в частности, s<sup>-2</sup>*m
  будут преобразованы в m/s<sup>2</sup>).

@sa sUnit, sUnits, sPhysValueField, sPhysRange.

*/


/*! Конструирует безразмерную физвеличину
    со значением 1 и погрешностью 0.

Но при этом размерность не объявляется фиксированной. Т.е. переменная или
член класса, инициированная этим "пустым" конструктором, сможет принимать
значения любой размерности.
Этот конструктор должен применяться лишь в весьма специфических случаях!

@sa FixTheUnits()
*/
sPhysValue::sPhysValue ()
    :sMathValue()
    ,TheUnits()
    ,UnitsAreFixedFlag(false)
    ,TheOrder(0)
    ,TheValueMantissa(1.0)
    ,TheErrorMantissa(0.0)
    ,PreciseFlag(true)
    ,ThePowerOfTenFlag(true)
    ,TheDigits(MaxDigits-1)
    ,NormalizationLevel(99)
{
}


sPhysValue::sPhysValue (std::istream &  a_stream ,rcsVersion  version)
    :sMathValue(a_stream,version)
    ,TheUnits(a_stream,version)
{
  a_stream.READ_INTO(UnitsAreFixedFlag);
  a_stream.READ_INTO(TheOrder);
  if( version < sVersion(1,5) ){
    realIOv14 R;
    a_stream.READ_INTO(R);  TheValueMantissa=R;
    a_stream.READ_INTO(R);  TheErrorMantissa=R;
  }else{
    realIO R;
    a_stream.READ_INTO(R);  TheValueMantissa=R;
    a_stream.READ_INTO(R);  TheErrorMantissa=R;
  }
  a_stream.READ_INTO(PreciseFlag);
  a_stream.READ_INTO(ThePowerOfTenFlag);
  a_stream.READ_INTO(TheDigits);
  a_stream.READ_INTO(NormalizationLevel);
}


void  sPhysValue::Store (std::ostream &  a_stream) const
{
  sMathValue::Store(a_stream);
  TheUnits.Store(a_stream);
  a_stream.WRITE_FROM(UnitsAreFixedFlag);
  a_stream.WRITE_FROM(TheOrder);
  realIO R;
  R=TheValueMantissa;  a_stream.WRITE_FROM(R);
  R=TheErrorMantissa;  a_stream.WRITE_FROM(R);
  a_stream.WRITE_FROM(PreciseFlag);
  a_stream.WRITE_FROM(ThePowerOfTenFlag);
  a_stream.WRITE_FROM(TheDigits);
  a_stream.WRITE_FROM(NormalizationLevel);
}


/*! Конструирует физвеличину, измеряемую в указанных единицах,
    со значением 1 и погрешностью 0.

Размерность объявляется фиксированной. Т.е. переменная или член класса,
инициированная этим конструктором, не сможет принимать значения в единицах, не
сопоставимых с заданными.

Заведомо безразмерные физвеличины тоже следует инициализировать этим
конструктором с константой RA::_Unitsless_ в качестве аргумента.

Поскольку единицы задаются выражением вида sUnits, это немного вычурный, но и
наиболее изящный (в смысле хорошего стиля программирования) способ инициализации
переменной или члена класса, при котором не плодятся строковые константы.
Например, так:
@code
  sUnits          WeightUnit ("pound");
  sUnits          SizeUnit ("feet");
  //...
  sPhysValue      Pressure (WeightUnit/(SizeUnit*SizeUnit));
  sPhysValue      ForseMoment (WeightUnit*SizeUnit);
  sPhysValue      Ratio (_Unitsless_);
@endcode

@sa sPhysValue::sPhysValue(sString).
*/
sPhysValue::sPhysValue (rcsUnits  units)
    :TheUnits(units)
    ,UnitsAreFixedFlag(true)
    ,TheOrder(0)
    ,TheValueMantissa(1.0)
    ,TheErrorMantissa(0.0)
    ,PreciseFlag(true)
    ,ThePowerOfTenFlag(true)
    ,TheDigits(MaxDigits-1)
    ,NormalizationLevel(1)
{
  Normalize(DraftNormalization);
}


/*!  Конструирует физвеличину, измеряемую в указанных единицах,
со значением @a value и погрешностью 0.

Остальное - как в sPhysValue::sPhysValue(rcsUnits).

@sa sPhysValue::sPhysValue(real,sString).
*/
sPhysValue::sPhysValue (real value ,rcsUnits  units)
    :TheUnits(units)
    ,UnitsAreFixedFlag(true)
    ,TheOrder(0)
    ,TheValueMantissa(value)
    ,TheErrorMantissa(0.0)
    ,PreciseFlag(true)
    ,ThePowerOfTenFlag(false)
    ,TheDigits(MaxDigits-1)
    ,NormalizationLevel(0)
{
  Normalize(DraftNormalization);
}


/*!  Конструирует физвеличину, измеряемую в указанных единицах,
со значением @a value и погрешностью @a error.

Остальное - как в sPhysValue::sPhysValue(rcsUnits).

@sa sPhysValue::sPhysValue(real,real,sString).
*/
sPhysValue::sPhysValue (real value ,real error ,rcsUnits  units)
    :TheUnits(units)
    ,UnitsAreFixedFlag(true)
    ,TheOrder(0)
    ,TheValueMantissa(value)
    ,TheErrorMantissa(std::abs(error))
    ,PreciseFlag( TheErrorMantissa == 0.0 )
    ,ThePowerOfTenFlag(false)
    ,TheDigits(MaxDigits-1)
    ,NormalizationLevel(0)
{
  Normalize(DraftNormalization);
}


/*!  Конструирует безразмерную физвеличину
     со значением @a value и погрешностью 0.

Переменная или член класса, инициированная этим конструктором, сможет принимать
только такие значения, которые могут быть приведены к безразмерному виду.

Эквивалентно конструкции sPhysValue(value,_Unitsless_), которая хоть и длиннее,
но лучше передаёт суть.
*/
sPhysValue::sPhysValue (real value)
    :TheUnits()
    ,UnitsAreFixedFlag(true)
    ,TheOrder(0)
    ,TheValueMantissa(value)
    ,TheErrorMantissa(0.0)
    ,PreciseFlag(true)
    ,ThePowerOfTenFlag(false)
    ,TheDigits(MaxDigits-1)
    ,NormalizationLevel(0)
{
  Normalize(DraftNormalization);
}


/*!  Конструирует безразмерную физвеличину
     со значением @a value и погрешностью @a error.

Переменная или член класса, инициированная этим конструктором, сможет принимать
только такие значения, которые могут быть приведены к безразмерному виду.

Эквивалентно конструкции sPhysValue(value,error,_Unitsless_), которая хоть и
длиннее, но лучше передаёт суть.
*/
sPhysValue::sPhysValue (real value ,real error)
    :TheUnits()
    ,UnitsAreFixedFlag(true)
    ,TheOrder(0)
    ,TheValueMantissa(value)
    ,TheErrorMantissa(std::abs(error))
    ,PreciseFlag( TheErrorMantissa == 0.0 )
    ,ThePowerOfTenFlag(false)
    ,TheDigits(MaxDigits-1)
    ,NormalizationLevel(0)
{
  Normalize(DraftNormalization);
}


/*!  Конструирует физвеличину, измеряемую в указанных единицах
     (единицы задаются в виде текстовой строки),
     со значением 1 и погрешностью 0.

Размерность объявляется фиксированной. Т.е. переменная или
член класса, инициированная этим конструктором, не сможет принимать
значения в единицах, не сопоставимых с заданными.

Это наиболее простой способ инициализации переменной:
@code
    sPhysValue      LightIntensity ("photon/s");
@endcode
или члена класса в его конструкторе:
@code
sMyClass::sMyClass ()
    :ThePeriod("s")
    ,TheStep("nm")
{
  //...
}
@endcode

@sa sPhysValue::sPhysValue(sUnits).
*/
sPhysValue::sPhysValue (sString  UnitsStr)
    :TheUnits(UnitsStr)
    ,UnitsAreFixedFlag(true)
    ,TheOrder(0)
    ,TheValueMantissa(1.0)
    ,TheErrorMantissa(0.0)
    ,PreciseFlag(true)
    ,ThePowerOfTenFlag(true)
    ,TheDigits(MaxDigits-1)
    ,NormalizationLevel(1)
{
  Normalize(DraftNormalization);
}


/*!  Конструирует физвеличину, измеряемую в указанных единицах
     (единицы задаются в виде текстовой строки),
     со значением @a value и погрешностью 0.

Остальное - как в sPhysValue::sPhysValue(sString).

@sa sPhysValue::sPhysValue(real,sUnits).
*/
sPhysValue::sPhysValue (real value ,sString  UnitsStr)
    :TheUnits(UnitsStr)
    ,UnitsAreFixedFlag(true)
    ,TheOrder(0)
    ,TheValueMantissa(value)
    ,TheErrorMantissa(0.0)
    ,PreciseFlag(true)
    ,ThePowerOfTenFlag(false)
    ,TheDigits(MaxDigits-1)
    ,NormalizationLevel(0)
{
  Normalize(DraftNormalization);
}


/*!  Конструирует физвеличину, измеряемую в указанных единицах
     (единицы задаются в виде текстовой строки),
     со значением @a value и погрешностью @a error.

Остальное - как в sPhysValue::sPhysValue(sString).

@sa sPhysValue::sPhysValue(real,real,sUnits).
*/
sPhysValue::sPhysValue (real value ,real error ,sString  UnitsStr)
    :TheUnits(UnitsStr)
    ,UnitsAreFixedFlag(true)
    ,TheOrder(0)
    ,TheValueMantissa(value)
    ,TheErrorMantissa(std::abs(error))
    ,PreciseFlag( TheErrorMantissa == 0.0 )
    ,ThePowerOfTenFlag(false)
    ,TheDigits(MaxDigits-1)
    ,NormalizationLevel(0)
{
  Normalize(DraftNormalization);
}


/*!  Конструктор копирования.

Делает то, что от него ожидается. В том числе копируется и UnitsAreFixedFlag.

@sa sPhysValue::operator = (rcsPhysValue).
*/
sPhysValue::sPhysValue (rcsPhysValue  R)
    :sAdam()
    ,sStorable()
    ,sMathValue()
    ,TheUnits(R.TheUnits)
    ,UnitsAreFixedFlag(R.UnitsAreFixedFlag)
    ,TheOrder(R.TheOrder)
    ,TheValueMantissa(R.TheValueMantissa)
    ,TheErrorMantissa(R.TheErrorMantissa)
    ,PreciseFlag(R.PreciseFlag)
    ,ThePowerOfTenFlag(R.ThePowerOfTenFlag)
    ,TheDigits(R.TheDigits)
    ,NormalizationLevel(R.NormalizationLevel)
{
//  RANet::Log.Put(sLog::Debug,"sPhysValue copy",Txt());
}


/*! @details
Если физвеличина не приводится к безразмерному виду, случится xRAlgebra.

Типичный пример использования:
@code
void Sleep (sPhysValue  time)
{
  real               T;
  try{
    T = ( time / sPhysValue("ms") ).ToReal();
    wait( int(T+0.5) ); //функции нужен целый параметр в миллисекундах
  }catch( rxRAlgebra ){
    //... ошибка: параметр time не в единицах времени!
  };
}
@endcode
При условии, что RA знает единицы "s" и "min", причём одна из них определена
как производная от другой, можно вызвать двухминутную паузу следующим образом:
@code
  Sleep(sPhysValue(2.0,"min"));
@endcode
*/
real  sPhysValue::ToReal () const
{
  sPhysValue                  R(_Unitsless_);
  R = (*this);
  return R.ValueMantissa()*power10(R.Order());
}


bool  sPhysValue::IsUnitsless () const
{
  try{
    ToReal();
    return true;
  }catch( rxRAlgebra ){
    return false;
  };
}


/*! Оператор присваивания.

Если в левой части стоит переменная с фиксированными единицами, то результат
вычисления выражения в правой части будет преобразован к этим единицам.  А если
преобразование невозможно, случится исключение вида xRAlgebra.
*/
rsPhysValue  sPhysValue::operator = (rcsPhysValue  R)
{
  real                        Ratio=1.0;
  if( ! UnitsAreFixedFlag ){
    TheUnits = R.TheUnits;
    TheOrder = R.TheOrder;
    TheValueMantissa = R.TheValueMantissa;
    TheErrorMantissa = R.TheErrorMantissa;
    PreciseFlag = R.PreciseFlag;
    ThePowerOfTenFlag = R.ThePowerOfTenFlag;
    TheDigits = R.TheDigits;
    NormalizationLevel = R.NormalizationLevel;
  }else if( TheUnits.Comparable(R.TheUnits,Ratio) ){
    TheOrder = R.TheOrder;
    TheValueMantissa = R.TheValueMantissa / Ratio;
    TheErrorMantissa = std::abs(R.TheErrorMantissa / Ratio);
    /*! @todo{PhysValues} PreciseFlag не везде обрабатывается */
    PreciseFlag = R.PreciseFlag;
    /*! @todo{PhysValues} ThePowerOfTenFlag = ?   */
    ThePowerOfTenFlag = R.ThePowerOfTenFlag && (Ratio == 1.0);
    NormalizationLevel = 0;
    Normalize(DraftNormalization);
  }else{
    RANet::Log.Put(sLog::Debug,"sPhysValue assign: ",Txt()+" =  "+R.Txt());
    throw xRAlgebra(sString("sPhysValue assign: ")+Txt()+" =  "+R.Txt()
                   ,__FILE__,__LINE__);
  };
  return *this;
}


/*! Установить погрешность.

@param error новая погрешность (единицы должны быть приводимы к единицам
             самой физвеличины).

@returns возвращает новое значение физвеличины с исправленной погрешностью.

*/
rsPhysValue  sPhysValue::SetError (rcsPhysValue  error)
{
  real                        Ratio=1.0;
  if( ! TheUnits.Comparable(error.TheUnits,Ratio) ){
    throw xRAlgebra("sPhysValue::SetError: incomparable units"
                   ,__FILE__,__LINE__);
  };
  Ratio *= power10(TheOrder-error.TheOrder);
  TheErrorMantissa = std::abs(error.TheValueMantissa / Ratio);
  PreciseFlag = (TheErrorMantissa == 0.0);
  NormalizationLevel = 0;
  Normalize(DraftNormalization);
  return *this;
}


rsPhysValue  sPhysValue::SetRelativeError (real  error)
{
  TheErrorMantissa = std::abs(error*TheValueMantissa);
  PreciseFlag = (error == 0.0);
  NormalizationLevel = 0;
  Normalize(DraftNormalization);
  return *this;
}


/*! Операция "меньше".

Хотел бы я знать, как правильно определить операции сравнения для чисел с
погрешностью!  Определил одну и самым тупым образом.

Но, по крайней мере, сравниваются значения, приведённые к одним единицам.
А если приведение невозможно, то случается исключение вида xRAlgebra.

*/
bool  sPhysValue::operator < (rcsPhysValue  R) const
{
  real                        Ratio=1.0;
  if( ! TheUnits.Comparable(R.TheUnits,Ratio) )
    throw xRAlgebra("sPhysValue::operator <: incomparable units"
                   ,__FILE__,__LINE__);
//  RANet::Log.Put(sLog::Debug,"Graph",sString("compare ")
//      +Txt()+"<"+R.Txt()+"    "
//      +(Value() < R.Value() / Ratio ? "Yes" : "No")
//      );
  return TheValueMantissa*power10(TheOrder)
       < R.TheValueMantissa*power10(R.TheOrder) / Ratio;
}


/*! Операция "унарный плюс". */
sPhysValue  sPhysValue::operator + () const
{
  return sPhysValue(*this);
}


/*! Операция "унарный минус". */
sPhysValue  sPhysValue::operator - () const
{
  sPhysValue                  Result(*this);
  Result.TheValueMantissa = - TheValueMantissa;
  Result.ThePowerOfTenFlag = false;
  return Result;
}


/*! Операция сложения.

Если единицы операндов сопоставимы, то результат получается в единицах
левого операнда. Если нет, то генерируется xRAlgebra.

Погрешность - по "школьной" формуле:
@code
      ∆(x+y) = ∆x + ∆y
@endcode
*/
sPhysValue  sPhysValue::operator + (rcsPhysValue  R) const
{
  real                        Ratio=1.0;
  if( ! TheUnits.Comparable(R.TheUnits,Ratio) )
    throw xRAlgebra("sPhysValue::operator +: incomparable units"
                   ,__FILE__,__LINE__);
  Ratio *= power10(TheOrder-R.TheOrder);
  sPhysValue                  Result(TheUnits);
  Result.TheOrder = TheOrder;
  Result.TheValueMantissa = TheValueMantissa + R.TheValueMantissa/Ratio;
  Result.TheErrorMantissa = TheErrorMantissa
                          + std::abs(R.TheErrorMantissa/Ratio);
  Result.ThePowerOfTenFlag = false;
  Result.NormalizationLevel = 0;
  Result.Normalize(DraftNormalization);
  return Result;
}


/*! Операция вычитания.

Если единицы операндов сопоставимы, то результат получается в единицах
левого операнда. Если нет, то генерируется xRAlgebra.

Погрешность - по "школьной" формуле:
@code
      ∆(x-y) = ∆x + ∆y
@endcode
*/
sPhysValue  sPhysValue::operator - (rcsPhysValue  R) const
{
  real                        Ratio=1.0;
  if( ! TheUnits.Comparable(R.TheUnits,Ratio) )
    throw xRAlgebra("sPhysValue::operator -: incomparable units"
                   ,__FILE__,__LINE__);
  Ratio *= power10(TheOrder-R.TheOrder);
  sPhysValue                  Result(TheUnits);
  Result.TheOrder = TheOrder;
  Result.TheValueMantissa = TheValueMantissa - R.TheValueMantissa/Ratio;
  Result.TheErrorMantissa = TheErrorMantissa
                          + std::abs(R.TheErrorMantissa/Ratio);
  Result.ThePowerOfTenFlag = false;
  Result.NormalizationLevel = 0;
  Result.Normalize(DraftNormalization);
  return Result;
}


/*! Операция умножения.

Погрешность - по формуле слегка улучшенной по сравнению со "школьной":
@code
      ∆(x*y) = |x*∆y| + |∆x*y| + ∆x*∆y
@endcode
где последний член существенен, когда относительная погрешность одного из
сомножителей больше или порядка единицы.
*/
sPhysValue  sPhysValue::operator * (rcsPhysValue  R) const
{
  sPhysValue                  Result(TheUnits);
  Result.TheOrder += Result.TheUnits.MultBy(R.TheUnits);
  Result.TheErrorMantissa = std::abs(TheValueMantissa * R.TheErrorMantissa)
                          + std::abs(TheErrorMantissa * R.TheValueMantissa)
                          + TheErrorMantissa * R.TheErrorMantissa      ;
  Result.TheValueMantissa = TheValueMantissa * R.TheValueMantissa;
  Result.TheOrder += TheOrder + R.TheOrder;
  Result.ThePowerOfTenFlag = false;
  Result.NormalizationLevel = 0;
  Result.Normalize(DraftNormalization);
  return Result;
}


/*! Операция деления.

Погрешность - по "школьной" формуле:
@code
      ∆(x/y) = |x/y| * ( |∆x/x| + |∆y/y| ) = |∆x/y| + |x*∆y/y/y|
@endcode

@todo{PhysValues} Надо бы поправить формулу для погрешности,
как это сделано для умножения, добавив члены второго порядка:
@a   +|∆x*∆y/y/y|+|x*∆y*∆y/y/y/y|,
а, может, и третьего, и, кроме того, отдельно рассмотреть ситуацию,
когда @a |∆y/y|>1 - результат NaN и @b специальное exception.
*/
sPhysValue  sPhysValue::operator / (rcsPhysValue  R) const
{
  /*! @todo{PhysValues} деление на ноль должно давать неопределенность,
                                                 а не плюс бесконечность*/
  sPhysValue                  Result(TheUnits);
  Result.TheOrder += Result.TheUnits.DivideBy(R.TheUnits);
  Result.TheErrorMantissa =
        std::abs(TheErrorMantissa / R.TheValueMantissa)
      + std::abs(TheValueMantissa * R.TheErrorMantissa / R.TheValueMantissa
                                                   / R.TheValueMantissa)
      ;
  Result.TheValueMantissa = TheValueMantissa / R.TheValueMantissa;
  Result.TheOrder += TheOrder - R.TheOrder;
  Result.ThePowerOfTenFlag = false;
  Result.NormalizationLevel = 0;
  Result.Normalize(DraftNormalization);
  return Result;
}


rsPhysValue  sPhysValue::operator += (rcsPhysValue  R)
{
  real                        Ratio=1.0;
  if( ! TheUnits.Comparable(R.TheUnits,Ratio) )
    throw xRAlgebra("sPhysValue::operator +=: incomparable units"
                   ,__FILE__,__LINE__);
  Ratio *= power10(TheOrder-R.TheOrder);
  TheValueMantissa += R.TheValueMantissa / Ratio;
  TheErrorMantissa += std::abs(R.TheErrorMantissa / Ratio);
  ThePowerOfTenFlag = false;
  NormalizationLevel = 0;
  Normalize(DraftNormalization);
  return *this;
}


rsPhysValue  sPhysValue::operator -= (rcsPhysValue  R)
{
  real                        Ratio=1.0;
  if( ! TheUnits.Comparable(R.TheUnits,Ratio) )
    throw xRAlgebra("sPhysValue::operator -=: incomparable units"
                   ,__FILE__,__LINE__);
  Ratio *= power10(TheOrder-R.TheOrder);
  TheValueMantissa -= R.TheValueMantissa / Ratio;
  TheErrorMantissa += std::abs(R.TheErrorMantissa / Ratio);
  ThePowerOfTenFlag = false;
  NormalizationLevel = 0;
  Normalize(DraftNormalization);
  return *this;
}


rsPhysValue  sPhysValue::operator *= (real  R)
{
  TheErrorMantissa = std::abs(TheErrorMantissa * R);
  TheValueMantissa *= R;
  ThePowerOfTenFlag = false;
  NormalizationLevel = 0;
  Normalize(DraftNormalization);
  return *this;
}


rsPhysValue  sPhysValue::operator /= (real  R)
{
  TheErrorMantissa = std::abs(TheErrorMantissa / R);
  TheValueMantissa /= R;
  ThePowerOfTenFlag = false;
  NormalizationLevel = 0;
  Normalize(DraftNormalization);
  return *this;
}


/*! Операция умножения на десять в степени @a order_shift.*/
rsPhysValue  sPhysValue::operator << (int  order_shift)
{
  TheOrder += order_shift;
  NormalizationLevel = 0;
  Normalize(DraftNormalization);
  return *this;
}


void  sPhysValue::Normalize (unsigned short int  level)
{
  if( level <= NormalizationLevel )
    return;
  RANet::Log.OpenBlock(sLog::Debug,"sPhysValue::Normalize",Txt());
  TheErrorMantissa = std::abs(TheErrorMantissa);
  if(       isnan(TheErrorMantissa) ){
    RANet::Log.Put(sLog::Info,"sPhysValue::Normalize","isnan(E)");
//!@todo{PhysValues} с этим получалось (-inf+-0)/(1+-0) -> -inf+-(-nan) -> nan+-inf
//    TheErrorMantissa = real_inf;
//    TheValueMantissa = real_nan;
  }else if( isinf(TheErrorMantissa) ){
    RANet::Log.Put(sLog::Debug,"sPhysValue::Normalize","isinf(E)");
    TheValueMantissa = real_nan;
  };
  if(       isinf(TheValueMantissa) ){
    if( level > 1 )  TheUnits.DissolveOrder(level);
    TheOrder = 0;
  }else if( isnan(TheValueMantissa) ){
    if( level > 1 )  TheUnits.DissolveOrder(level);
    TheOrder = 0;
  }else if( (TheValueMantissa == 0) && (TheErrorMantissa == 0) ){
    if( level > 1 )  TheUnits.DissolveOrder(level);
    TheOrder = 0;
    TheDigits = MaxDigits;
  }else{
    int                         Shift = 0;
    bool                        TryToIncreaseExpectedRest = false;
    int                         ExpectedRest = 0;
    real                        C = 1.0;
    //приведение мантисс: V к [0.1,1) или если |V|<E, то E к [0.1,1)
    //и вычисление максимального сдвига,
    //допустимого после приведения единиц
    {
      if( std::abs(TheValueMantissa) < TheErrorMantissa ){
        RANet::Log.Put(sLog::Debug,"sPhysValue::Normalize","|V|<E");
        real                        LgE = log10(TheErrorMantissa);
        if( LgE == - real_inf ){
          RANet::Log.Put(sLog::Debug,"sPhysValue::Normalize","LgE=-inf");
        }else if( LgE == real_inf ){
          RANet::Log.Put(sLog::Debug,"sPhysValue::Normalize","LgE=+inf");
        }else if( isnan(LgE) ){
          RANet::Log.Put(sLog::Debug,"sPhysValue::Normalize","LgE=NaN");
        }else{
          Shift = floor(LgE)+1;
        };
      }else{
        real                        LgV = log10(std::abs(TheValueMantissa));
        if( LgV == -real_inf ){
          RANet::Log.Put(sLog::Debug,"sPhysValue::Normalize","LgV=-inf");
        }else if( LgV == real_inf ){
          RANet::Log.Put(sLog::Debug,"sPhysValue::Normalize","LgV=+inf");
        }else if( isnan(LgV) ){
          RANet::Log.Put(sLog::Debug,"sPhysValue::Normalize","LgV=NaN");
        }else{
          Shift = floor(LgV)+1;
        };
        TryToIncreaseExpectedRest = true;
      };
    };
    if( Shift != 0 ){
      C = power10(Shift);
      TheValueMantissa /= C;
      TheErrorMantissa /= C;
      TheOrder += Shift;
    };
    if( TryToIncreaseExpectedRest ){
      if( TheErrorMantissa < 0.1 )  ExpectedRest = 1;
      if( TheErrorMantissa < 0.01 )  ExpectedRest = 2;
      if( TheErrorMantissa < 0.001 )  ExpectedRest = 3;
    };
    if( level > 1 ){
      TheOrder = TheUnits.DissolveOrder(level,TheOrder
                                       ,ExpectedRest-2,ExpectedRest);
    };
    if( TheOrder < 0 ){
      Shift = TheOrder - floor(TheOrder/3)*3;
    }else{
      Shift = TheOrder - floor((TheOrder-1)/3)*3;
    };
    if( Shift != 0 ){
      TheOrder = TheOrder - Shift;
      C = power10(Shift);
      TheValueMantissa *= C;
      TheErrorMantissa *= C;
    };
    real                        D = log10(0.3/TheErrorMantissa);
    TheDigits = ( D > MaxDigits ? MaxDigits
                                : ( D < 0 ? 0 : ceil(D) ) );
  };
  NormalizationLevel = level;
  RANet::Log.Put(sLog::Debug,"sPhysValue::Normalize",sString("finally ")+Txt());
  RANet::Log.CloseBlock(sLog::Debug,"sPhysValue::Normalize");
}


/*! @details
Может иметь побочный эффект - нормализацию.

Сравни с sPhysValue::Text(eTextFormat,eTextDetalization)const.
С++ умеет подставлять ту или иную в зависимости от объявления объекта.
*/
sString  sPhysValue::Text (eTextFormat        format
                          ,eTextDetalization  detalization)
{
//  RANet::Log.Put(sLog::Debug,"sPhysValue::Text","");
  if( NormalizationLevel < BriefNormalization ){
    Normalize(BriefNormalization);
  };
  return Txt(format,detalization);
}


/*! @details
Без побочного эффекта, так как для нормализации использует копию. К сожалению,
при этом полезная работа по нормализации пропадает.

Сравни с sPhysValue::Text(eTextFormat,eTextDetalization).
С++ умеет подставлять ту или иную в зависимости от объявления объекта.
*/
sString  sPhysValue::Text (eTextFormat        format
                          ,eTextDetalization  detalization ) const
{
//  RANet::Log.Put(sLog::Debug,"sPhysValue::Text","const");
  if( NormalizationLevel < BriefNormalization ){
    sPhysValue                  NormalizedForm(*this);
    NormalizedForm.Normalize(BriefNormalization);
    return NormalizedForm.Txt(format,detalization);
  }else{
    return Txt(format,detalization);
  };
}


sString  sPhysValue::Txt (eTextFormat        format
                         ,eTextDetalization  detalization) const
{
  sString                     T;
  sString                     UT;
  if( isinf(TheValueMantissa) || isnan(TheValueMantissa) ){
    T = sString::FromReal(TheValueMantissa,TheDigits);
  }else if( detalization == Verbose ){
    (T = "(") += sString::FromReal(TheValueMantissa,TheDigits+1) + " ± "
               + sString::FromReal(TheErrorMantissa,TheDigits+1) + ")";
  }else if( ThePowerOfTenFlag && (detalization == Laconic) ){
  }else{
    T = sString::FromReal(TheValueMantissa,TheDigits);
  };
  if( TheOrder ){
    if( format == HTML ){
      if( ! T.Empty() )  T += Symbol::Multiplication;
      T += "10<sup>";
    }else if( detalization == Verbose ){
      if( ! T.Empty() )  T += "*";
      T += "1e";
    }else{
      T += "e";
    };
    T << TheOrder;
    if( format == HTML ){
      T += "</sup>";
    };
  };
  UT = TheUnits.Text(format);
  if( ! UT.Empty() ){
    T += " ";
    T += UT;
  };
  return T;
}

//------------------------------------------------------------------------------
} //namespace RA