Discussion of the possibility of conflicting information on some pages on the documentation

 

I started this thread to move a discussion being had on another thread (that was getting way off topic for the thread) so that other people can chime in on what their opinion is regarding this thought.  Are there pages (such as documentation or others) that have conflicting information on them?  I believe so, specifically the page for the function of MathRound() at https://docs.mql4.com/math/mathround.

My last post I said was going to be the end of it, and to keep that true, I am moving what I was going to post there to here instead.

So to not tie up another post with this, making response to Gum's answer at https://www.mql5.com/en/forum/156144/page3#1017734 here.

Gum in specific response to your "rounded off to the nearest integer" line, that is exactly what it means.  It doesn't change the value the integer was obtained from, that is still a double (or float, or whatever it was before the value of it was sent to the function).  It rounds it to an integer, as it says, and then returns a double, which is not what it says it is supposed to do unless you cast it as one as the example shows.  As far as being the only one confused about it, I am not confused at all.  I understand very clearly that it uses casts it to double in the example, and I also understand very clearly that at two different spots in the rest of the page, it says integer.

1 sample code of casting (basically forcing) it to type double + 2 times saying integer (and all 3 on the same page) = Not Clearly Defined.

On my post with the Java and C++ examples, they were both clearly written examples of what is returned.  In the case of the C++, even though it returned a float, it clearly stated it.  The wording on the MQL code for MathRound is not clear that it returns a double, it is presumed by some, and it does so in this case, especially if you tell it by type cast to return a double as it does in the code example.  If it supposed to return a double, then it should not have integer in either of the two areas where it says it returns an integer or "value rounded off to the nearest integer" or any variation that includes integer, and the doc page needs to be corrected.  If it can return multiple types depending on what type value is sent to it, then it should show that as well.  If it is supposed to return an integer as the doc page says, then the code of the function needs to be corrected so that it actually returns the integer it says it does.


The MathRound doc page is not the only example of conflicting information.  There is also apparently conflicting information on the signals rules page at https://www.mql5.com/en/signals/rules.  My specific examples.

In https://www.mql5.com/en/signals/rules#part_III titled Setting up a signal and relevant subscription, item number 11. "Signals based on real accounts are available only by paid Subscription; signals based on demo accounts can be received only by free Subscription."  But in https://www.mql5.com/en/signals/rules#part_II (on the same page), titled Signals Providers, item number 9, "The Signals Provider is entitled to transmit Trading Signals via the "Signals" service on a free of charge basis."  So, does that mean that the signals provider CAN allow free subscriptions from section 2, but then has to charge for them if they are using a real account?  If it is up to the signal provider in one section of the rules, why isn't it in the other section that is on the same page?  Or is it that they can still offer a subscription for free but only if they are using a demo account?  What if someone who is trading on a live account wants to provide signals for others to follow free of charge, in agreement with the rule stated in section 2?  That should be something stated either the same way in both spots or in a way that doesn't appear to be conflicting.  Such as, in item nine, add "subject to certain conditions" at the end.  Possible conflicting information.

 

The description of MathRound could be a little better but it is clear enough to almost everyone here. Integer has two meanings. The mathematical one , and a datatype. On this page they are using the mathematic meaning, whereas you are always picking the 'datatype' meaning.

JD4: > I understand very clearly that it uses casts it to double in the example,

There is no evidence that it 'casts' anything, only that it returns a double. it might always remain a double datatype. I suspect the FPU has an instruction to do this (round a number to the nearest integer(mathematical meaning) whilst it remains a float datatype (it does see end)-

Integer 

  • meaning 1: integer = whole number   
  • meaning 2: integer - a datatype that holds a subset of whole numbers.

We dont get this confusion with real numbers because different words are used for the datatype...

  • real = a number   real number is a value that represents a quantity along a continuous line (from wiki)
  • double = a data type that holds a subset , and approximation to a real number. 

 It's simple if you can read an integer as just being a whole number without always thinking 'datatype'

 

JD4: the wording on the MQL code for MathRound is not clear that it returns a double, it is presumed by some, and it does so in this case, especially if you tell it by type cast to return a double as it does in the code example 

 Now that is just getting silly. If the above is your position there is really no point discussing it further. There is no presumption. From MathRound page. It's clear in the prototype definition. It is not a really code example, it is a prototype definition. Do you understand the difference ?

double  MathRound(
   double  value      // value to be rounded
   );

 

 

 * PS I looked up the x86 FPU Round instruction - its called FRNDINT - Any half decent compiler/language/application on x86 platform (C, Java,Excel,Pascal,Perl,Python, etc ) will use this instruction to round a float to an integer (read 'whole number' not 'datatype'). The description...

FRNDINT rounds the contents of ST0 to an integer, according to the current rounding mode set in the FPU control word, and stores the result back in ST0. 

Now ST0 is a floating point register - so it is a float that contains an integer (whole number) . Just like the MQL page - integer simply means 'whole number'.

 

MathRound() is a function

As with any function, the return value type must be described in the function header. The return value type for MathRound() is described as a double. Therefore it can only return a double.

Please read the documentation on functions 

Functions

Every task can be divided into subtasks, each of which can either be directly represented in the form of a code, or divided into smaller sub-tasks. This method is called stepwise refinement. Functions are used for writing the code of sub-tasks to be solved. The code that describes what a function does is called function definition:

function_header
  {
   instructions
  }

All that is before the first brace is the header of the function definition, and what is between braces is the body of the function definition. The function header includes a description of the return value type, name (identifier) and formal parameters.  The number of parameters passed to the function is limited and cannot exceed 64.

The function can be called from other parts of the program as many times as necessary. In fact, the return type, function identifier and parameter types constitute the function prototype.

Function prototype is the function declaration, but not its definition. Due to the explicit declaration of the return type and a list of argument types, the strict type checking and implicit typecasting are possible during function calls. Very often function declarations are used in classes to improve the code readability.

The function definition must exactly match its declaration. Each declared function must be defined.

Example:

double                       // return value type
linfunc (double a, double b) // function name and parameter list
  {
                             // composite operator
   return (a + b);           // return value
  }

 

The return operator can return the value of an expression located in this operator. If necessary, the expression value is converted to the function result type. What can be returned: simple types, simple structures, object pointers. With  the return operator you can't return any arrays, class objects, variables of compound structure type. 

 No matter what you feel that a value is cast to during the execution of the function, note the highlighted above -"If necessary, the expression value is converted to the function result type". The function result type is clearly described as a double.

 

Response to knave's comment at https://www.mql5.com/en/forum/156144/page3#1017744 first.

It does not clearly state it returns a double, the example only clearly shows casting it as a double.  Why do you think we specify to use an int or a float or a double?  The line above the example still says it rounds to an integer, as does the section marked Return Value further down in the page.  It doesn't say it returns "a double of an integer value."  The example is coded to type cast it to a double, that is the only thing I agree with you about. When you look at OrderSend, it also doesn't say integer in one place, and double in another.  Regarding your comment about the ticket number, it returns a ticket number.  If the system can use a ticket number that is just an integer or float or whatever, that can return it, then it returns that.  If it says in one spot it returns an integer and in another it returns a double, then that is a problem as well, and that also needs to be fixed.


@ ydrol - "There is no evidence that it 'casts' anything, only that it returns a double. it might always remain a double datatype. I suspect the FPU has an instruction to do this (round a number to the nearest integer(mathematical meaning) whilst it remains a float datatype (it does see end)-"    I disagree, since the example code clearly casts it, or if you want to use other terms that mean the same thing, it directs it, it instructs it to return a double.

Code example given on the page

double  MathRound(
   double  value      // value to be rounded
   );

That double word is what casts it to a double, and that is the evidence, which has been posted repeatedly by people who do not see it being cast as a double but a normal operation, despite the two other spots on the same page that say Integer.  When creating arrays or variables or programmer built constants or methods or functions, how do you tell the system what data type you want it to use in each of those situations?  By the use of the type cast, be it string, int, float, long, short, char, whatever.  That is all that is happening here, by using that double in front of the function name, you are explicitly instructing the function being called to return a double.  In Gum's examples above, the type of double is being stated as the desired return type, so it is reasonable to want a return type of double. 

"The function returns a value rounded off to the nearest integer of the specified numeric value." and "Value rounded till to the nearest integer."

(ydrol quote) "Now that is just getting silly. If the above is your position there is really no point discussing it further. There is no presumption. From MathRound page. It's clear in the prototype definition. It is not a really code example, it is a prototype definition. Do you understand the difference ?"

I agree, constant refusal by many to see the return type clearly states integer, and the line right after the title clearly states integer, is silly.  But somehow, me pointing this out means that I am the one with the issue.

It is only a prototype definition in the broadest terms.  But as far as the presumption, I agree, there is no presumption.  I am not presuming anything.  I am letting the page speak for itself.  It returns a double when the parts of the page that say return value say it should return an int.  It is either a poorly chosen code example or the doc page needs to be corrected.  If the function is supposed to return an int as it says in the two other spots on the page, then the function code needs to be repaired.  If it can return multiple types, then the code example and the rest of the page needs to show that.  If it is supposed to return a double as you claim, the doc page needs to be corrected to show clearly in the first line of the page and the Return Value that it "returns a double".


If you really want to see presumption, how about this.  How about you imagine a situation where you have a documentation page, you don't know what the function is called, doesn't really matter for this example anyway.  You just know it has to do with math, calculating numbers, something related.  But you can see the part that says "Return Value", so from that, you can presume that the information below tells you what that function will send back when it is called, presuming, obviously, that the code is written properly.  Now, in that section of the page, you see "Value rounded till to the nearest integer."  Wouldn't it be reasonable to presume that it returns a value rounded to the nearest integer?  Wouldn't it also be reasonable to presume that, because an integer, by it's definition hopefully we can at least agree on, is a whole number (positive, negative, and zero), has no fractions, no decimals, no "hangers-on" to borrow a phrase?  Now isn't it also reasonable to presume that how a computer program, when using something so defined as an integer, would use, and here's a wild idea, an int data type to hold that integer that was returned?  All of these presumptions are reasonable when given in this example, and yet you are expecting a different response when all of these same things are true on the mathround function doc page.


"If necessary, the expression value is converted to the function result type."  Thank you for posting this, because it helps accent my point that if you instruct it to return a double, as the code example given on the page does, then it can reasonably be expected to return a double.  That is one of the wonderful things about an object oriented programming style.  You can overload operators (some) and functions to operate differently depending on what information or values are being sent to them.  Like the print function, if you send it an int value, it will use the part of it's code that processes integers; if you send it a string, it will use the part of it's code to process a string, etc.


The value being sent to the function was never a question or a problem.  If a function was well built and designed to work that way, you would be able to send it multiple choices of values.  Since this one is supposed to be rounding to the nearest integer, you would not be out of line to expect that you could send a variety of numeric non-integer data types to it.  However, it would be out of line to expect it's default operation to not return an integer if it says it returns an integer.  By casting the return type to double as the code example does, then it would not be out of line to expect a double to be returned because you are telling it to return a double by doing that.


"No matter what you feel that a value is cast to during the execution of the function, note the highlighted above -"If necessary, the expression value is converted to the function result type". The function result type is clearly described as a double."  It is not what I feel it is being cast to, the code IS casting it to that.  Once again, if you tell a function (and it is capable of doing so) that you want it to return a double, you can expect it to return a double.  The function return type, according to the section of the page that specifies it, says integer, so the function return type is clearly an integer.  You are basing that statement on the example given alone, not what the page says in the return type.


"Now ST0 is a floating point register - so it is a float that contains an integer (whole number) . Just like the MQL page - integer simply means 'whole number'."    Because the computer is capable of floating point arithmetic, this is not unreasonable.  You wouldn't want it to send your calculations to something only capable of holding an int type if you needed to also calculate floats and doubles.  Besides, the register is only what the computer program stores the value in.  That has very little to do with the type the program uses for the variable, other than it needs to be able to calculate it accurately.  Computer programming, for the most part, needs to have accurate information, unless you are specifically just gathering generalities.  Let's say you have a program that, because the coder was not as precise as they needed to be, only loses a few million dollars.  But that must be OK because the coder was expecting the function he called to return a certain data type that the documentation said it did, but it returned something different.  It only throws off the rest of the program.  But that is OK, because the documentation for the function said one thing and the function actually did another.  If a function returns a type of double, then why does it not state that in the section marked "return type"?

 

Once again (because you clearly dont understand ) ...

 

 ydrol: Now that is just getting silly. If the above is your position there is really no point discussing it further. There is no presumption. From MathRound page. It's clear in the prototype definition. It is not a really code example, it is a prototype definition. Do you understand the difference ?

 

If necessary, the expression value is converted to the function result type" 

As WHRoeder would say - what part of 'If necessary" don't you understand ? You have two fundamental problems:

1. you are still unable to read integer as a mathematical concept rather than a computing datatype. If you could there would be no confusion. << This is your biggest mistake here

2. The function doesn't have to cast anything unless the intermediate result is a different datatype. ("if necessary" ) - In this case I'm pretty sure that an FPU machine code instruction will round 2.4 to integer 2.0 (the mathematical term not the datatype) while it remains a double.

 

For sake of argument imagine a function

double MathPrime(double n)  - returns the largest prime number smaller than n.

 I know that MathPrime(6.0) returns a double 5.0 

 But guess what - Prime numbers are by definition a subset of 'integers' (the mathematical concept), but you would look silly arguing that has to be  casting an integer datatype to a double, because you have no visibility of how the function works. - it could internally be a lookup table of doubles for example

My MathPrime function has nothing to do with the 'integer' (datatype) , even though it must return an integer(maths). 

Same with MathRound.  

 

There is also a 3rd problem.  straw man arguments. Eg. ...

  JD4: If a function returns a type of double, then why does it not state that in the section marked "return type"?

There is no section 'Return Type' It actually says:

docs: Return Value

Value rounded till to the nearest integer.  << 'integer' here is the mathematical concept not the computing datatype.

This actually makes me begin to think you are in denial :)  The 'code example' as you like to call it - is the prototype. This clearly states the return type. 

 

One last try.

   
   //In main code
   Print("test=",test() );  

 

//function
double test()
 {
 int a=10;
 return(a);
 }

 Do you expect the test function to return an integer 10 or a double 10.0 ?

Please give the reason for your answer (preferably in less than 20 words) 

 

JD4 a function specially for you. This returns value rounded to the nearest integer (mathematically). (for +ve x) Please tell me at which point it casts from one datatype to another, and the before and after datatypes of the cast.

Also please explain why the result is not an integer (as a mathematical concept).

double MathRound4JD4(double x) {

 double d = 0.0;

while ( d <= x ) d += 1.0;

 return ( d - 1.0);

} 

 

One more ...  

// MathEven returns largest even integer  <= x. for +ve x = - again   - as even numbers are by definition integers - please explain at which point it is casting data types, and the before and after types. Also explain how it can return even numbers (which are integers) if there are no casts to integer (datatype).

double MathEven(double x) {

 double d = 0.0;


while ( d <= x ) d += 2.0;

 return ( d - 2.0);

}
 
ydrol:

Once again (because you clearly dont understand ) ...

 

As WHRoeder would say - what part of 'If necessary" don't you understand ? You have two fundamental problems:

1. you are still unable to read integer as a mathematical concept rather than a computing datatype. If you could there would be no confusion.

2. The function doesn't have to cast anything unless the intermediate result is a different datatype. ("if necessary" ) - In this case an FPU machine code instruction will round 2.4 to integer 2.0 (the mathematical term not the datatype) white it remains a double.

 

For sake of argument imagine a function (changed slightly from original post so it would show here proper)

double MathPrime(double n);  // returns the largest prime number smaller than n.

 I know that MathPrime(6.0) returns a double 5.0 

 But guess what - Prime numbers are by definition a subset of 'integers' (the mathematical concept), but you would look silly arguing that has to be  casting an integer datatype to a double, because you have no visibility of how the function works. - it could internally be a lookup table of doubles for example

My MathPrime function has but this is nothing to do with the 'integer' (datatype) , even though it must return an integer(maths). 

Same with MathRound.  

 

 

I clearly understand fine.  It is either bad function code or bad documentation page.  You are right, the function doesn't have to cast, but the example does because the doc page states integer, not double, in the return type.  If that is not the place to specify that it returns a double type, then where is?  The example, in programming language, clearly tells the function "hey, I want you to send me back a double data type" by use of the word double in the call to the function.  Have you ever called a function without specifying a return type?  I think lots of people have, and not even realized it.  The below line calls a function.  No need to specify a return type because it does not need one.

   Print("File Header Written Correctly");

The code sample from function doc page https://book.mql4.com/operators/function

Return_value_type Function_name (List of formal parameters)//Header
   {                                    // Opening brace
   Program code                         // A function body may consist ..
   composing the function               //.. of operators and ..
   body                                 //.. calls to other functions
   }                                    // Closing brace

By using the code this way, you are telling the function being called what type you want returned.  With the print example, is not necessary to specify a return type because of how the function is built to operate.  That is called default behavior, which it will do if you do not specify a return type.  The code for the function will sometimes figure out what to send back without being told a specific type to return, based on it's design, if it is coded properly.

1.  I understand integer as a mathmatical concept just fine, but we are talking about data types and programming code, not concepts.  If you want to talk about concepts, math related or otherwise, a discussion about a doc page for a programming language function isn't really the place for it.  A doc page is supposed to accurately state what the function does, if there are any special notes, what data the function takes, what it returns, etc.  If it doesn't state it accurately, as it does not in this case, then it needs to be corrected.  If the function IS supposed to operate the way the doc page says, and it doesn't in this case, then the code within the function needs to be corrected.  It is a simple concept to grasp, programs sometimes have errors and those errors need to be corrected.  It is called debugging.

2. You are right, under certain circumstances, you would not have to cast the return type of a function, unless you specifically wanted to change it to something other than what it was designed for.  That is how we can code a function to have a default behavior.  Within the function should be the ability to accept the expression value and convert it to the default function return type (my wording so it was clear).  In this case the code example type casts to double because it should automatically return an int, as the rest of the page says it does.

In your MathPrime example, it returns a double because you are explicitly telling it to return a double by the type word double in front of calling the function.  It does not get to choose to return a default type because by telling it in the programming code you want a double returned, that is what it does.

As far as having visibility of how the function works, we don't need to.  That is a part of the OOP idea.  We just need to know that the function works, we could care less how, unless it doesn't work as advertised.  We see from the doc page what the function name is, what it is supposed to do, what data type(s) it is expected to return, what inputs it is able to take.  And a spot for any notes to let the programmer know of any special circumstances that might be there.

On this doc page (MathRound function), the actual behavior (it returns a double) does not match the expected documented behavior (return of an int).  You need to look at the stated return type to decide what it is supposed to return over a poorly written code sample.  If all you have is a generic code sample, then go with that, but that is not the case here.

Simply stated, as I have said from the beginning, either the doc page or the function code is broken and needs to be fixed.

 

  I understand integer as a mathmatical concept just fine, but we are talking about data types and programming code, not concepts.

Another straw man argument to support your position. You are assuming the MathRound page is using one definition of integer, when it clearly makes perfect sense using the other.

On this doc page (MathRound function), the actual behavior (it returns a double) does not match the expected documented behavior (return of an int).

The page does not say that anywhere. You know it , we all know it.  The document clearly says the return type is double. (via prototype), and the return value is "Value rounded till to the nearest integer. "  is the mathematical definition of integer. It's simple.

With hindsight I'm annoyed at myself for typing this much. Must stop. Continue with your blinkers.. 

 
ydrol:

Another straw man argument to support your position. You are assuming the MathRound page is using one definition of integer, when it clearly makes perfect sense using the other.

I am not assuming anything.  I am expecting a programming language documentation page to do it's job properly, be the documentation page for a specific piece of the programming language, and accurately document the code it is for.  As I said, this is a discussion about the code, not a concept.  Concepts are fine within programming in discussions on how to get something done.  We are discussing the specifics of the page, not a concept about the page or a concept about something on the page.


ydrol:

The page does not say that anywhere. You know it , we all know it.  The document clearly says the return type is double. (via prototype), and the return value is "Value rounded till to the nearest integer. "  is the mathematical definition of integer. It's simple.

Don't know if I should say it does say that (integer) there or to your second part, so I went with second because it is a more concrete example. 

Except for the fact that it doesn't.  It says integer.  Twice.  Once at the top, and once on the page in the area specifically marked return type.  It doesn't say "double" in the area marked return type, it doesn't say "double via prototype" there either, it says "integer."  I have posted it so many times, as have many others, not going to post it yet again because people can't wrap their head around the word integer because the poor code example uses double.  The only place it "says" double is in the code example.  The examples are supposed to demonstrate proper use and support the rest of the page, not brow beat the rest of the page into saying something different.  You even post the part with "integer" specifically in it, and still cannot seem to grasp the contradiction present on the page.

 

Last one for you... as you like C++ so much , I guess you have the same 'issues' with this page...

floor double floor (double x); Rounds x downward, returning the largest integral value that is not greater than x.

And on the same site...

is_integral  Trait class that identifies whether T is an integral type.

A C++ site happily using 'integral' mathematically in one context , and as a datatype in another. I suggest you pester them also.

and here and here 

Right must get back to my EA that will make me rich beyond my wildest dreams ...