Help File/Documentation Issues. (Discussion Only)

[water]

I do not think this is sensible as the documentation in section "function notes" clearly states: 

Quote

If a function uses the @error flag method, the flag should be checked immediately after the function returns as @error will be reset to 0 when entering the next function. No attempt to use or access the function return value should be made if the @error flag has been set as in that case the return value is generally undefined...

 

[jpm]

if the doc say failure = @error the @error must be check first so don't do any thing if the doc is correct

[argumentum]

4 hours ago, water said:

...if the @error flag has been set as in that case the return value is generally undefined...

un·de·fined /ˌəndəˈfīnd/  [adjective] not clear or defined. My English sucks.
So to be clear ( in my head ), if there is an error, don't trust the return, because there was an error.

 

3 hours ago, jpm said:

if the doc say failure = @error the @error must be check first so don't do any thing if the doc is correct

Well, then the doc is misleading. Actually, the documentation say that the 1st entry in the array is -1 if failure but the return is an integer. Hence the code and the explanation are in conflict. 

To wrap it up:
If there is an error, don't trust the return. Makes sense.
The return of a function that had an error will return nonsense, because there was an error and the error flag say that there was one.
If the expectation of a return is an integer and returns one, you get one back, but in this case the expectation is an array.
Say, in 

Func _NowDate()
    Local $tLocalTime = _Date_Time_GetLocalTime()
    If @error Then Return SetError(@error, @extended, "")
    Return _DateTimeFormat($tLocalTime.Year & "/" & $tLocalTime.Month & "/" & $tLocalTime.Day, 0)
EndFunc   ;==>_NowDate

on error here, the return is an empty string and that makes sense. And will not crash a script. I don't think that anyone checks for an error in this function, ever.

in this one:

Func _Date_Time_FileTimeToDOSDateTime($tFileTime)
    Local $aDate[2]
    Local $aCall = DllCall("kernel32.dll", "bool", "FileTimeToDosDateTime", "struct*", $tFileTime, "word*", 0, "word*", 0)
    If @error Then Return SetError(@error, @extended, $aDate)
    $aDate[0] = $aCall[2]
    $aDate[1] = $aCall[3]
    Return SetExtended($aCall[0], $aDate)
EndFunc   ;==>_Date_Time_FileTimeToDOSDateTime

is also good. If there is an error, the flag is set and returns an empty array.

All I propose is to have that type of consistency in  _Date_Time_GetTimeZoneInformation() ( as described in the help file )
Now given that the array may have nonsense ( from the DllCall ), to return an empty array like in this:

ConsoleWrite(@CRLF & Test()[0] & @TAB & @error & @CRLF & @CRLF)
Func Test()
    Return SetError(10, 0, __DateEmptyArray(8, -1))
EndFunc

; #FUNCTION# ====================================================================================================================
; Author ........: Paul Campbell (PaulIA)
; Modified.......: Gary Frost (gafrost); argumentum
; ===============================================================================================================================
Func _Date_Time_GetTimeZoneInformation()
    Local $aInfo[8] = [-1]
    Local $tTimeZone = DllStructCreate($tagTIME_ZONE_INFORMATION)
    Local $aCall = DllCall("kernel32.dll", "dword", "GetTimeZoneInformation", "struct*", $tTimeZone)
    If @error Then Return SetError(@error, @extended, __DateEmptyArray(8, -1))
    If $aCall[0] = -1 Then Return SetError(10, 0, __DateEmptyArray(8, -1))

    $aInfo[0] = $aCall[0]
    $aInfo[1] = DllStructGetData($tTimeZone, "Bias")
    $aInfo[2] = DllStructGetData($tTimeZone, "StdName")
    $aInfo[3] = __Date_Time_CloneSystemTime(DllStructGetPtr($tTimeZone, "StdDate"))
    $aInfo[4] = DllStructGetData($tTimeZone, "StdBias")
    $aInfo[5] = DllStructGetData($tTimeZone, "DayName")
    $aInfo[6] = __Date_Time_CloneSystemTime(DllStructGetPtr($tTimeZone, "DayDate"))
    $aInfo[7] = DllStructGetData($tTimeZone, "DayBias")
    Return $aInfo
EndFunc   ;==>_Date_Time_GetTimeZoneInformation

Func __DateEmptyArray($iSize, $v1stValue = "")
    Local $aArray[$iSize] = [$v1stValue]
    Return $aArray
EndFunc   ;==>__DateEmptyArray

would be best, because the array has a return from a DllCall, and may be "dirty" so, we return an empty array that satisfies the spirit of the function, the expected error as per the help file, and would not crash the script, as the cherry on top.

The only reason to keep it as is ( don't touch it ), is beyond me. And would happily welcome a response that obliterates my trend of thought. Am actually begging for one that does.

[donnyh13]

Greetings:
My apologies if this has been reported before elsewhere, but in the new help file for AutoIt 3.3.18.0, I think there is a broken table in the “StringRegExp” Help, under the “"whitespaces characters" and *UCP dependencies” section? Perhaps I am mistaken, but it looks a little bit hard to read at least.
Thanks,
Best Regards,

[pixelsearch]

@donnyh13 Hi
 
When we discussed this with @jchd and @jpm in Trac Ticket #3945 then the last table at the end of the web page showed the results with a better alignment, I'm pasting it below :

Row   Unicode CharacterName                \h   \v   \s  [[:space:]] [[:blank:]]
--------------------------------------------------------------------------------
# 1   0x0009  HT                           xX        xX      xX          xX
# 2   0x000A  LF                                xX   xX      xX
# 3   0x000B  VT                                xX   xX      xX
# 4   0x000C  FF                                xX   xX      xX
# 5   0x000D  CR                                xX   xX      xX
# 6   0x0020  SPACE                        xX        xX      xX          xX
# 7   0x0085  NEL                               xX    X       X
# 8   0x00A0  NO-BREAK SPACE               xX         X       X           X
# 9   0x1680  OGHAM SPACE MARK             xX         X       X           X
# 10  0x180E  MONGOLIAN VOWEL SEPARATOR    xX         X       X           X
# 11  0x2000  EN QUAD                      xX         X       X           X
# 12  0x2001  EM QUAD                      xX         X       X           X
# 13  0x2002  EN SPACE                     xX         X       X           X
# 14  0x2003  EM SPACE                     xX         X       X           X
# 15  0x2004  THREE-PER-EM SPACE           xX         X       X           X
# 16  0x2005  FOUR-PER-EM SPACE            xX         X       X           X
# 17  0x2006  SIX-PER-EM SPACE             xX         X       X           X
# 18  0x2007  FIGURE SPACE                 xX         X       X           X
# 19  0x2008  PUNCTUATION SPACE            xX         X       X           X
# 20  0x2009  THIN SPACE                   xX         X       X           X
# 21  0x200A  HAIR SPACE                   xX         X       X           X
# 22  0x2028  LINE SEPARATOR                    xX    X       X
# 23  0x2029  PARAGRAPH SEPARATOR               xX    X       X
# 24  0x202F  NARROW NO-BREAK SPACE        xX         X       X           X
# 25  0x205F  MEDIUM MATHEMATICAL SPACE    xX         X       X           X
# 26  0x3000  IDEOGRAPHIC SPACE            xX         X       X           X

Legend :
xX  will match with or without (*UCP) in the pattern
X   alone will match ONLY if (*UCP) is present at the start of the pattern

For example let's create a subject starting with "abc" followed by a no-break space (0x00A0) and ending with "def" , so the subject looks like this "abc def" (make sure there is a no-break space in the middle of the subject between abc and def) . Now let's test different patterns :

=======================
2 patterns searching for \h
abc\hdef  => 1 match
(*UCP)abc\hdef => 1 match

Both patterns match because xX is indicated for \h  (concerning the no-break space)

=======================
2 patterns searching for \s
abc\sdef       => NO match
(*UCP)abc\sdef => 1 match

Only the pattern starting with (*UCP) matches because X is indicated for \s  (concerning the no-break space)

This example could be applied to any of the 26 characters found in the table above
Hope it helps

[donnyh13]

Thanks @pixelsearch,

That explains what i'm seeing very well. I thought initially that a table wasn't formatted right in the html.

I really appreciate your example and time explaining it.

Best regards,

 

[jchd]

Indeed, all these buggy @DOUBLE_WS make this table terribly hard to read. Even copy-pasting the table content to a text editor and replacing @DOUBLE_WS by a couple of spaces doesn't align the columns.

I confess being responsible for going deep into (*UCP) details in StringRegEx help (beside having authored the bulk of that help topic) but since we DO have AutoIt users handling cyrillic, greek, asian languages and others, I found it useful to mention everything of value for all users.

[jpm]

3 hours ago, jchd said:

Indeed, all these buggy @DOUBLE_WS make this table terribly hard to read. Even copy-pasting the table content to a text editor and replacing @DOUBLE_WS by a couple of spaces doesn't align the columns.

I confess being responsible for going deep into (*UCP) details in StringRegEx help (beside having authored the bulk of that help topic) but since we DO have AutoIt users handling cyrillic, greek, asian languages and others, I found it useful to mention everything of value for all users.

I am working to fix the double_ws

[donnyh13]

11 hours ago, jchd said:

I confess being responsible for going deep into (*UCP) details in StringRegEx

Its great having in-depth detail on these things, so it's not so much that, that I was referring to (Sorry I wasn't clear), but rather the Table alignment, and as you said the "@DOUBLE_WS " etc. Thanks very much for everyone's work on the help file. It has helped a million times.