forum.alglib.net
http://forum.alglib.net/

Discrepancies between the documentation and implementation.
http://forum.alglib.net/viewtopic.php?f=2&t=4353
Page 1 of 1

Author:  RockBrentwood [ Fri Jul 24, 2020 2:25 am ]
Post subject:  Discrepancies between the documentation and implementation.

In the free C++ version of ALGLIB in each API function, a parameter X of type T is documented as either:
(A) T X
(B) T &X
while it is declared and implemented respectively as
(A) const T X, for scalar types (T = bool, ae_int_t, double, complex)
(A) const T &X, for all other types T
(B) T &X
except that the parameters for call-back functions are documented exactly as they are implemented and required.

A note should be made of the convention used in (A), perhaps also with a link https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rf-in ("in-parameter passing with constant references", Stroustroup et al.) where it is discussed in greater depth.

However, there are exceptions and possible discrepancies. Parameters of the 1D and 2D array types T = {boolean,integer,real,complex}_{1,2}d_array may sometimes be documented as (B) but implemented and declared as (A). This occurs with the following parameters in the following routines:
∙ a 14 routines:
rmatrixenforcesymmetricity, rmatrixger, spdmatrixcholeskyupdate{add1,fix}[buf], xdebug{b{1,2}not,{c,i,r}{1,2}neg}

∙ b 20 routines:
rmatrix{[gen]copy,transpose}, {r,c}matrix[lu]solve[m]fast, rvectorcopy, {h,s}pdmatrix[cholesky]solve[m]fast

∙ c 5 routines:
cmatrixherk, {r,c}matrix{gemm,syrk}

∙ tmp 1 routine:
rmatrixsyvmv

∙ x 7 routines:
{r,c}matrix{left,right}trsm, rmatrixtrsv, sparsetr{m,s}v

∙ xy 2 routines:
rankdata[centered]

∙ y 4 routines:
rmatrix[ge,sy]mv, sparsegemv

or in 53 routines in all. I assume that these are unintentional discrepancies, and in our local version of the documentation, the declarations are changed from (B) T &X to (A) T X to reflect the declaration and implementation.

Finally, the declarations of the xy parameter disagree between the short and long versions, each, of the routines rankdata() and rankdatacentered():

∙ void rankdata(const real_2d_array &xy, const ae_int_t npoints, const ae_int_t nfeatures);
void rankdata(real_2d_array &xy);

∙ void rankdatacentered(const real_2d_array &xy, const ae_int_t npoints, const ae_int_t nfeatures);
void rankdatacentered(real_2d_array &xy);

which I assume was also unintentional. In the local version the declarations xy in the short forms were changed to (A) parameters:

∙ void rankdata(const real_2d_array &xy);

∙ void rankdatacentered(const real_2d_array &xy);

However, since they were documented as (B) parameters, then it's possible you may have intended that the declarations implementations of xy in the long forms match, instead, as (B) parameters to:

∙ void rankdata(real_2d_array &xy, const ae_int_t npoints, const ae_int_t nfeatures);

∙ void rankdatacentered(real_2d_array &xy, const ae_int_t npoints, const ae_int_t nfeatures);

Page 1 of 1 All times are UTC
Powered by phpBB © 2000, 2002, 2005, 2007 phpBB Group
http://www.phpbb.com/