Help for Number(): What is Double number?

[c.haslam]

I read in the help for Number():

Valid characters for Double numbers does not start the stripping

What is a Double number? Based on experimentation, I wonder whether it is a number in hexadecimal notation.

 

[guinness]

Google broken?

Wikipedia: https://en.wikipedia.org/wiki/Double-precision_floating-point_format (in other words a double number is 1 (.0 is implied) or 3.14 or 99.99

[c.haslam]

Thank you for clarifying. I saw that the first character of Double is upper-case, so I wondered whether there was some special significance. 

To save you looking it up, here is the whole of the Remarks for Number():

If you pass number, function outputs the input.
A string beginning with letters has a numeric value of zero. A string beginning with digits has non-numeric characters stripped at the from the first one. Valid characters for Double numbers does not start the stripping.
Default behavior results in auto-sized integer. If input value after conversion is within the range of 32bit integer the result is 32bit integer. If not the result is 64bit integer. Both are signed.

Perhaps you may agree that from the second sentence on, there is a slightly lack of clarity. Further, I cannot make sense of A string beginning with digits has non-numeric characters stripped at the from the first one.

Please consider the following examples:

Number("3.14")  ; Returns 3.14
Number("24/7")  ; Returns 24
Number("24cat")     ; Returns 24
Number("1,000")     ; Returns 1
Number("tmp3")  ; Returns 0
Number("1.2e3sa")   ; Returns 1200
Number("1.2e3sa")   ; Returns 51934
Number("0xcade")    ; Returns 12
Number("0xcpox")    ; Returns 0

I have been advised on Trac to post stuff on the Forum, seeking comments and advice, before creating a Ticket. So that is what I am doing.

From the examples, I see that Valid characters for Double numbers does not start the stripping  depends on the previous sentence which is missing one or more words.

To me, it seems that valid characters for Double numbers are the same ones that are valid for numbers that can be stored as single-precision (32-bit). So is 3.14 stored as a double-precision number?  If input value after conversion is within the range of 32bit integer the result is 32bit integer. If not the result is 64bit integer.  suggests not.

I am prepared to suggest Remarks that reflect what actually happens, either here or on Trac.

If you would prefer, I will desist from making suggestions about the documentation.

Edited July 16, 2015 by c.haslam

[guinness]

I agree the remarks could do with clarifying as well as the example being changed a bit ($b is now for boolean data types). What do you have in mind?

[c.haslam]

Guinness,

After a couple of hours of work, here is my suggestion for Number() > Remarks :

expression is a string. If the string contains only a number, the result is the number. The number may be an integer, or be in floating-point, scientific, or hexadecimal notation.

If the string is an arithmetic expression involving only integers,  + and/or -, the result is calculated. If one of the numbers is in floating-point or scientific notation, the result is the first number.

If the string begins with a number but continues with other characters, the result is the number. The number must be an integer, or in floating-point or scientific notation.

In the above cases, the function returns an integer if the mantissa of the result is zero or flag is $NUMBER_32BIT or $NUMBER_64BIT . These flags truncate a floating-point result.

In all other cases, 0 is returned.

The default for an integer result is to store it in 32 bits if possible. If not, it is stored in 64 bits.

I am realizing that you and I see the role of documentation differently. To me, documentation should be clear, complete, and concise. It should be written in the context of the user. 

Much of the documentation for AutoIt is fine, but there places where it needs work, but I am thinking that I may not be offering further suggestions for UDF help pages in the light of recent rejection (without reason given) of my suggestion for _ArraySwap(). I believe in giving as well as receiving, but there are limits. I do realize that we are both volunteers.

 

[guinness]

I am realizing that you and I see the role of documentation differently. To me, documentation should be clear, complete, and concise. It should be written in the context of the user. 

Not true, you just have to look around and see that since I came on board many trac tickets and posts have been made towards improving the help file. So I don't think that's a justifiable comment to make. My number one priority is improving the examples and documentation, whilst at the same time introducing standards to be adopted in AutoIt (like PSR-0 in PHP).

When I read the Number() remarks myself, I felt it was lacking in clarity, hence why I asked if you had a suggestion for improving, as the help file is a community project, even though a few of us have access to svn. It's just the same as if we were to host it on github, only a couple of us would be able to merge the pull requests.

Much of the documentation for AutoIt is fine, but there places where it needs work, but I am thinking that I may not be offering further suggestions for UDF help pages in the light of recent rejection (without reason given) of my suggestion for _ArraySwap().

Fair point. I have updated the ticket with my reasoning behind it. If you would like me to explain further then I would be much obliged to do so.

As for you suggestion, thanks very much. I have tweaked it a little bit and updated the example too. You might want to check your comments again to your example, as not all the numbers were correct.

#include <AutoItConstants.au3>
#include <MsgBoxConstants.au3>

Local $dNumber1 = Number(1 + 2 + 10) ; Returns 13.
Local $dNumber2 = Number("3.14") ; Returns 3.14.
Local $dNumber3 = Number("24/7") ; Returns 24.
Local $dNumber4 = Number("tmp3") ; Returns 0 as this is a string.
Local $dNumber5 = Number("1,000,000") ; Returns 1 as it strips everything after (and including) the first comma.
Local $dNumber6 = Number("24autoit") ; Returns 24
Local $dNumber7 = Number("1.2e3sa") ; Returns 1200
Local $dNumber8 = Number("0xcade") ; Returns 51934

MsgBox($MB_SYSTEMMODAL, "", "The following values were converted to a numeric value:" & @CRLF & _
        "$dNumber1 = " & $dNumber1 & @CRLF & _
        "$dNumber2 = " & $dNumber2 & @CRLF & _
        "$dNumber3 = " & $dNumber3 & @CRLF & _
        "$dNumber4 = " & $dNumber4 & @CRLF & _
        "$dNumber5 = " & $dNumber5 & @CRLF & _
        "$dNumber6 = " & $dNumber6 & @CRLF & _
        "$dNumber7 = " & $dNumber7 & @CRLF & _
        "$dNumber8 = " & $dNumber8 & @CRLF)

Note: A number is consider a value that is either an integer, floating-point value, scientific or hexadecimal notation.

If the string contains a number, the result will be a number.
If the string contains an arithmetic expression with a number at the beginning of the expression, then this value will be returned as a number, will all other value being ignored.
If the string begins with a number but continues with additional non-number characters, the number part is returned as a number only.
If the expression parameter is an arithmetic expression, then expression will be evaluated first before returning the result as a number.
If all other cases 0 is returned.

In the above cases, the function returns an integer if the mantissa of the result is zero or flag is $NUMBER_32BIT or $NUMBER_64BIT. These flags will truncate a floating-point result.

The default for an integer result is to store it in 32 bits if possible. If not, it is stored in 64 bits.

[jchd]

expression is a string.

No, expression can be any AutoIt expression (and not only arithmetic).

Number("1.2e3sa")   ; Returns 51934   <-- no, 1200
Number("0xcade")    ; Returns 12      <-- no, 51934

A string beginning with digits has non-numeric characters stripped at the from the first one.

There was an extra "the" here. Hex strings use a different convention:
 

ConsoleWrite(Number("0xc") & @LF)       ; Returns 12
ConsoleWrite(Number("0xc3") & @LF)      ; Returns 195
ConsoleWrite(Number("0xc34") & @LF)     ; Returns 3124
ConsoleWrite(Number("0xc3x") & @LF)     ; Returns 0
ConsoleWrite(Number("0xc3 x") & @LF)    ; Returns 0

If the string is an arithmetic expression involving only integers,  + and/or -, the result is calculated. If one of the numbers is in floating-point or scientific notation, the result is the first number.

I don't get that: "+ and/or -" that should be "signed or not"

ConsoleWrite(Number("-+1") & @LF)    ; Returns 0

If the string begins with a number but continues with other characters, the result is the number. The number must be an integer, or in floating-point or scientific notation.

Hex strings need a more complete explanation, as shown above.

In the above cases, the function returns an integer if the mantissa of the result is zero or flag is $NUMBER_32BIT or $NUMBER_64BIT . These flags truncate a floating-point result.

The flag $NUMBER_AUTO has wrong explanation: it can give a FP value. But I don't believe one should say "truncation":

ConsoleWrite(Number("0.9999999999999999") & @LF)    ; Returns 1

 

Edited July 17, 2015 by jchd

[guinness]

@jchd, did you see my changes above?

[Melba23]

Hi,

I was working on this earlier today - here is my suggested text:

If "expression" is a number or arithmetic expression in integer, floating-point, scientific or hex notation, the output is the number or the result of the evaluated expression.

If "expression" is a string containing only a number or arithmetic expression the result is the number or the result of the expression. A string will be read (and if necessary evaluted) only as far as the first non-numeric character (see flag remarks below) - if the first character is non-numeric the function returns 0.

If the input is entirely integer in format, the return will default to 32-bit format (64-bit if too large).

When the $NUMBER_32BIT/$NUMBER_64BIT flags are set, the return is forced into the corresponding integer form. If "expression" is a string then setting either of these flags means that any non-digit character other than a leading unary minus will truncate the string - when other flags are set the function will accept decimal point, scientific and hex notation characters within a string.

M23 

[jchd]

guinness,

Yes I saw it but I was busy typing my post with this awfully slow editor and that took "some" time.

Unary plus should be mentionned as well. Also a word on hex conversion failing to zero when a non-hex digit found in the hex part (past "0x"). Then "expression" can be any AutoIt expression or variable type; it's then converted to its numeric value or zero when such conversion isn't possible or sensible.

ConsoleWrite(Number(Ptr(5)) & @LF)  ; Returns 5
ConsoleWrite(Number(Binary("abc")) & @LF)   ; Returns decimal value of 0x616263 = 6513249
ConsoleWrite(Number(ObjCreate("Scripting.Dictionary")) & @LF)   ; Returns 0
ConsoleWrite(Number(1 > 3 Or 5 <= 15) & @LF)    ; Returns 1

 

[guinness]

Done. Thanks.

[c.haslam]

I was off doing other things for a while. I think Melba's text is better than mine, so when guinness wrote "Done" I expect that he meant that Mebla23's version was accepted.

I do note one typo in his text: evaluted => evaluated.

But, on my machine:

ConsoleWrite(Number("12*3")&@CRLF)    ; Returns 12
ConsoleWrite(Number('12.4 + 23.3')&@CRLF)    ; Returns 12.4
ConsoleWrite(Number("12/3")&@CRLF)    ; Returns 12
ConsoleWrite(Number('12 + 34 + 23/15')&@CRLF)    ; Returns 12
ConsoleWrite(Number(" 12*3")&@CRLF)    ; Returns 12
ConsoleWrite(Number("12^3")&@CRLF)    ; Returns 12
ConsoleWrite(Number('0xc + 0x2')&@CRLF)    ; Returns 0

So it appears to me that Number() accepts neither * nor / nor ^ nor numbers in floating-point notation, nor numbers in hex notation, as part of an arithmetical expression.

So perhaps the following should be inserted into Melba23's text :

 If an arithmetic expression contains mathematical operators other than + and -, or a floating-point number, the string is read only to the end of the first number. A number in hex notation causes the function to return 0.

[guinness]

When I said done, I meant I amended my version. Melba23 is free to change the text in the help file if they so wish, as jchd pointed out that both our texts are missing some important details and I don't want to step on Melba23's toes.

Anyway, I hope you can now see I appreciate you pointing out the issue with Number(). Thanks.

###Remarks###
Note: A number is consider a value that is either an integer, floating-point value, scientific or hexadecimal notation.

If the string contains a number, the result will be a number.
If the string contains an expression (AutoIt or variable type) with a number at the beginning of the expression, then this value will be returned as a number, will all other value being ignored.
If the string begins with a number but continues with additional non-number characters, the number part is returned as a number only.
If the expression parameter is an arithmetic expression, then expression will be evaluated first before returning the result as a number.
If hexadecimal notation, but values passed 0x are non-hexadeciaml (0-9, A-F), then 0 is returned.
If unary plus/minus is used e.g. +30 or -30, then this will be returned as their positive and negative counterparts.
If all other cases 0 is returned.

In the above cases, the function returns an integer if the mantissa of the result is zero or flag is $NUMBER_32BIT or $NUMBER_64BIT. These flags will truncate a floating-point result.

The default for an integer result is to store it in 32 bits if possible. If not, it is stored in 64 bits.

Edited July 17, 2015 by guinness

[guinness]

I meant this had errors.

Number("3.14")  ; Returns 3.14
Number("24/7")  ; Returns 24
Number("24cat")     ; Returns 24
Number("1,000")     ; Returns 1
Number("tmp3")  ; Returns 0
Number("1.2e3sa")   ; Returns 1200
Number("1.2e3sa")   ; Returns 51934 <= Should be 1200
Number("0xcade")    ; Returns 12 <= Should be 51934
Number("0xcpox")    ; Returns 0

 

[c.haslam]

OK. Mea culpa.

[guinness]

Just learnt some Latin today!