_ArraySwap() suggestion for doc rejected

[c.haslam]

guinness,

You wrote in the thread on Number():

... 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.

 I agree completely.

You also wrote in Ticket 3080:

Instinctively one thinks geometrically: horizontal (X) axis and then vertical (Y) axis. This is not, however, the case with a 2D array, rows come first and then columns.

You are correct, however ...

The function is:

_ArraySwap ( ByRef $aArray, $iIndex_1, $iIndex_2 [, $bCol = False [, $iStart = -1 [, $iEnd = -1]]] )

Consider swapping 2 columns in rows of a 2D array. $iIndex_1 and $iIndex_2 are row indexes. $iStart and $iEnd are columns indexes. To me, it would be clearer (and would give me more confidence in the function) if the description of $iStart and $iEnd said column/row rather than row/column. Also, when coding, it would remind me to call the function with row indexes for $iIndex_1 and $iIndex_2, and column indexes for $iStart and $iEnd..

So there are good reasons to write column/row for the last 2 parameters.

I also note that the defaults for $iStart and $iEnd are not mentioned in Parameters. Perhaps the following should be added to Remarks:

For 2D arrays, $iStart defaults to 0 and $iEnd defaults to the highest column/row index in $aArray.

I discovered these point when, in a recent project, I needed to swap two columns in all rows. As a user, I am cautious about using someone else's function;   _ArraySwap() didn't look friendly, so I need to establish whether it is trustworthy. I started to look at the source code, to check whether $iIndex_1 and $iIndex_2 were reversed with $iStart and $iEnd, met the first few lines of code and saw that I would need to dig through array indexes; made a mental note to suggest improvements in the doc, and decided that understanding the code would delay progress on the project, so wrote my own function.

I remember now that I also glanced at the example. Perhaps I would have gained confidence in _ArraySwap if the last part of the example had looked like this:

$aArray = $aArray_Base
_ArraySwap($aArray, 3, 7)
_ArrayDisplay($aArray, "Swapped rows 3 and 7 in all columns", Default, 8)

$aArray = $aArray_Base
_ArraySwap($aArray, 3, 7, False, 2, 5)
_ArrayDisplay($aArray, "Swapped Rows 3 and 7 in Cols 2 to 5", Default, 8)

$aArray = $aArray_Base
_ArraySwap($aArray, 3, 7, True)
_ArrayDisplay($aArray, "Swapped Cols 3 and 7 in all rows", Default, 8)

$aArray = $aArray_Base
_ArraySwap($aArray, 3, 7, True, 2, 5)
_ArrayDisplay($aArray, "Swapped Cols 3 and 7 in Rows 2 to 5", Default, 8)

As always, these suggestions are yours to accept or reject.

 

[Melba23]

c.haslam,

I wrote _ArraySwap and the associated Help file page, so I hope Guinness will forgive me if I answer in his place.

----------------------

Firstly, thanks for the compliments - very much appreciated:

_ArraySwap() didn't look friendly, so I need to establish whether it is trustworthy

(and would give me more confidence in the function)

Perhaps I would have gained confidence in _ArraySwap

Pretty much an object lesson in how NOT to write a request for a change to something.

----------------------

Passing quickly to the points you wish to make: 

- 1.

it would be clearer [...] if the description of $iStart and $iEnd said column/row rather than row/column

I do not agree. The parameter list makes it quite clear whether the user is swapping a row or column with "$iIndex_1/$iIndex_2":

$bCol: [optional] If True then for 2D array above parameters refer to rows;
                  if False (default) above parameters refer to columns

If the user cannot remember whether a row or column was used for "$iIndex_1/$iIndex_2" then I do not feel that altering the order of "row/column" in the parameter remarks for "$iStart/$iEnd" will have any effect, or even be noticed. In fact, I would suggest that having mix of "row/column" and "column/row" on the same page is likely to lead to even more confusion that already appears to be the case for you (although no-one else to date).

- 2: I will certainly adjust the comments on the examples along the lines that you suggest.

----------------------

Anyway as you say you:

wrote my own function

 I suggest you stick with that and let others who have fewer problems in understanding 25 lines of code use the library function.

M23

Edit: Altered example comments committed.

Edited July 18, 2015 by Melba23

[guinness]

I wrote _ArraySwap and the associated Help file page, so I hope Guinness will forgive me if I answer in his place.

I have no issue. I missed this post the first time around anyway.

[Jos]

It is quite remarkable how people think they can come here and make these firm judgements about the work done by others and then assuming they will bend over or something.
Anybody that has put in this much effort to help building autoit3 to the level it is today, will for sure have an initial reaction of " Screw you too" and rightly so.

It is fine to have suggestions and even criticism, but @c.haslam, it is not justified to write the way I have seen you do quite regularly now.
I must say both guinness and Melba23 have responded very mildly as I would have simply ignored all your stuff by now.
First just reflect on this for a while before posting any emotional reaction!

Jos

Edited July 18, 2015 by Jos

[c.haslam]

Noted

[c.haslam]

Understood