Modified version of the standard Array.au3 include file

[BrewManNH]

I have a modified version of the standard Array.au3 file that comes with AutoIt3. Most of the original _Arrayxxx functions didn't/don't support 2D arrays when using them. I have welded on the ability to use most of the existing functions with a 1 or 2D array. There are a couple of the _Array functions that I have not added this functionality to, mostly because I don't think it would be necessary and/or helpful for them to have it.

Here is a list of the functions included in the Array.au3 file that have been added and modified, taken from the header of the file

; #CURRENT# =====================================================================================================================
;_ArrayAdd *
;_ArrayBinarySearch *
;_ArrayCombinations
;_ArrayConcatenate *
;_ArrayDelete
;_ArrayDisplay *
;_ArrayFindAll
;_ArrayInsert *
;_ArrayMax *
;_ArrayMaxIndex
;_ArrayMin *
;_ArrayMinIndex
;_ArrayPermute
;_ArrayPop *
;_ArrayPush *
;_ArrayReverse *
;_ArraySearch
;_ArraySort
;_ArraySwap
;_ArrayToClip *
;_ArrayToString *
;_ArrayTrim *
;_ArrayUnique (Corrected the header information)
; * - #MODIFIED FUNCTIONS#
; ===============================================================================================================================
; #NEW FUNCTIONS ADDED# =========================================================================================================
;_ArrayAddColumns
;_ArrayDeleteColumn
;_ArrayMaxIndex2D
;_ArrayMinIndex2D
; ===============================================================================================================================

These modified functions are a drop in replacement for the original functions, they are backwards compatible with all scripts written to use the functions as originally written, but I have added the ability to use them with 2D arrays, as well as with 1D arrays. 2 of the new functions weren't written by me, _ArrayAddColumns and _ArrayDeleteColumn, but I have them in my arsenal of array functions so I figured it couldn't hurt to include them here as well. If anyone finds these useful, please let me know. If anyone finds any problems or bugs, I'd like to know that as well. Hopefully I have updated all of the function comment headers to reflect the changes, but if I have missed something let me know about that too so I can correct it.

As an added bonus, I am also posting an array related function called _FileWriteFromArray2D, which will write a 2D array to a file and is a modified version of _FileWriteFromArray that only works with 1D arrays. This could probably be incorporated into the _FileWriteFromArray function so that it would be able to handle 1D and 2D arrays natively pretty easily.

expandcollapse popup

; #FUNCTION# ====================================================================================================================
; Name...........: _FileWriteFromArray2D
; Description ...: Writes Array records to the specified file.
; Syntax.........: _FileWriteFromArray2D($File, $a_Array[, $i_Base = 0[, $i_UBound = 0[, $cDelim]]])
; Parameters ....: $File     - String path of the file to write to, or a file handle returned from FileOpen().
;                 $a_Array  - The array to be written to the file.
;                 $i_Base   - Optional: Start Array index to read, normally set to 0 or 1. Default=0
;                 $i_Ubound - Optional: Set to the last record you want to write to the File. default=0 - whole array.
;                 $cDelim   - Optional: Delimiter character used to separate subitems in a row
; Return values .: Success - Returns a 1
;                 Failure - Returns a 0
;                 @Error  - 0 = No error.
;                 |1 = Error opening specified file
;                 |2 = Input is not an Array
;                 |3 = Error writing to file
;                 |4 = Array is not 2 dimensional
; Author ........: Jos van der Zande <jdeb at autoitscript dot com>
; Modified.......: Updated for file handles by PsaltyDS at the AutoIt forums.
; Remarks .......: If a string path is provided, the file is overwritten and closed.
;                 To use other write modes, like append or Unicode formats, open the file with FileOpen() first and pass the file handle instead.
;                 If a file handle is passed, the file will still be open after writing.
; Related .......: _FileReadToArray
; Link ..........:
; Example .......: Yes
; ===============================================================================================================================
Func _FileWriteFromArray2D($File, $a_Array, $i_Base = 0, $i_UBound = 0, $cDelim = "|")
    ; Check if we have a valid array as input
    If Not IsArray($a_Array) Then Return SetError(2, 0, 0)
    ; determine last entry
    Local $last = UBound($a_Array) - 1, $iSubItem = UBound($a_Array, 2), $sFileWrite
    If $i_UBound < 1 Or $i_UBound > $last Then $i_UBound = $last
    If UBound($a_Array, 0) <> 2 Then Return SetError(4, 0, 0)
    If $i_Base < 0 Or $i_Base > $last Then $i_Base = 0
    ; Open output file for overwrite by default, or use input file handle if passed
    Local $hFile
    If IsString($File) Then
        $hFile = FileOpen($File, 2)
    Else
        $hFile = $File
    EndIf
    If $hFile = -1 Then Return SetError(1, 0, 0)
    ; Write array data to file
    Local $ErrorSav = 0
    For $x = $i_Base To $i_UBound
        $sFileWrite = ""
        For $i = 0 To $iSubItem - 1
            $sFileWrite &= $a_Array[$x][$i] & $cDelim
        Next
        $sFileWrite = StringTrimRight($sFileWrite, StringLen($cDelim))
        If FileWrite($hFile, $sFileWrite & @CRLF) = 0 Then
            $ErrorSav = 3
            ExitLoop
        EndIf
    Next
    ; Close file only if specified by a string path
    If IsString($File) Then FileClose($hFile)
    ; Return results
    If $ErrorSav Then Return SetError($ErrorSav, 0, 0)
    Return 1
EndFunc   ;==>_FileWriteFromArray2D

11/10/2011 - Updated attachment

Ran #AutoIt3Wrapper_Au3Check_Parameters=-d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w 7 on the contents of the file to eliminate any warning messages that might be popping up.

No functional changes to the functions, just cleaning up the mess of warning messages that didn't affect the working of the script, but might make the unwary nervous about them. All warnings have been fixed by declaring the variables correctly.

_Array.au3

Edited November 10, 2011 by BrewManNH

[Spiff59]

This could probably be incorporated into the _FileWriteFromArray function so that it would be able to handle 1D and 2D arrays natively pretty easily.

There is something similar in BugTracker #1712, which is marked completed. But I'm not sure if just the 1-line fix to the existing routine, or the 1D/2D version was utilized.

PS - Nice work!

PPS - I hope parts of the Array.au3 UDF someday fade into oblivion. It seems a bloated UDF with functions of little use like ArrayCombinations, ArrayPermute, ArrayReverse, etc. There are also a slew of functions that only replace 3-5 lines of basic code, like ArraySwap, ArrayPop, ArrayMin(Index), ArrayMax(Index), etc. ArrayTrim probably fits into both categories

Edited August 9, 2011 by Spiff59

[BrewManNH]

I was going through the Array.au3 file looking at some of the functions in it and wondering to myself if they are ever used. I'm sure they have uses to people, but I can't see me using them myself.

I got the urge one day to "fix" the _ArrayBinarySearch function so that I could use it on a 2D array because I didn't want to have to recreate the subitem in a separate array just to search it quicker than by using _ArraySearch. Once I had that one finished, I looked through the rest of the function list to see which ones could be "fixed" to work with more than just a 1D array and that is how I ended up with this modified version.

[Spiff59]

I got the urge one day to "fix" the _ArrayBinarySearch function

The array search, sort, and I/O functions are certainly keepers! Ones worth the effort to maintain and enhance.

I'm suprised that some of the others got by the watchful (critical) eye of Valik!

Func _ArrayPop(ByRef $Array)
    Local $i = UBound($Array) - 1, $str = $Array[$i]
    ReDim $Array[$i]
    Return $str
EndFunc

Edit: Added one (adjective) lol

Edited August 9, 2011 by Spiff59

[water]

I really like the idea of an enhanced UDF which supports 1D and 2D arrays.

I think users should be called to replace the original Array.au3 with your UDF and test their scripts. Results should be published here so you can see how good your UDF works.

Maybe after some time of testing your code could replace the official UDF.

[BrewManNH]

I wouldn't complain about that. I mention this thread whenever anyone posts about the 1/2D array issues. I'm not sure how else to "promote" it.

[jmon]

I really like the idea of an enhanced UDF which supports 1D and 2D arrays.

I think users should be called to replace the original Array.au3 with your UDF and test their scripts. Results should be published here so you can see how good your UDF works.

Maybe after some time of testing your code could replace the official UDF.

I tested it with 2 of my scripts and I haven't found any issue or bug. It was very simple to update the existing script with this modified version.

I think this modified version should be part of the next autoit update !

[guinness]

I just downloaded as I was creating a quick script but didn't want the hassle of creating my own _ArrayInsert for a 2D array, this has a lot of potential. Thanks.

One thing I would say is use this #AutoIt3Wrapper_Au3Check_Parameters=-d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w 7 at the top of the script to check that it passes Au3Check.

Edited November 10, 2011 by guinness

[BrewManNH]

Are you saying to add that ( #AutoIt3Wrapper_Au3Check_Parameters=-d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w 7) to the _Array.au3 file, or to the scripts that use it?

[Melba23]

BrewManNH,

Add the line to the _Array.au3 script and run a syntax check to see if there are any problems with the UDF code. Fix them until you get a clean check. Then comment it out on release - or else lazy coders will never get any scripts to run at all as you will force the check on all their code!

M23

[BrewManNH]

I have updated the attachment in the original post with all corrections made that were causing warnings to show up during Au3Check. No changes to how the functions work, just declaring variables in the various functions correctly.

[guinness]

Thanks Melba23 for explaining I was a little late in replying and I can just see the comments now "my code shows an error but there isn't an error."

BrewManNH,

Have you never ran these parameters with your own code before?

[BrewManNH]

I have, but didn't on this because I didn't think of it. Also, I tend to not make that kind of error when coding.

Most of what I modified was just adding the checks for 2D arrays and the functions to use them. Reusing the variable names caused 90% of the warnings because I originally developed them as a standalone function for 2D arrays only and then when I got them working, I merged them into the original Array.au3 file. Pretty much the only warnings that were showing up were the ones about variables already being declared, moving the declaration outside of the If...Then statements was all that was needed.

[Melba23]

BrewManNH,

Also, I tend to not make that kind of error when coding

Tempting fate a bit there, in my opinion!

M23

[BrewManNH]

What's life without a bit of fate tempting now and then? Coding on the edge, at my age and condition it's about the best I can do.

[BrewManNH]

It appears that the bonus function that I added to this thread (_FileWriteFromArray2D) isn't necessary because the beta versions of AutoIt, since version 3.3.7.0, has changed the _FileWriteFromArray function to support 1 and 2D arrays. It's not mentioned in any of the help file or changelog entries for the function but if you look at the bug tracker entry 1712 you will see it mentioned in there that to correct a crash issue with the function when it's sent a 2D array Spiff59 added 2D array support to the function which was added to File.AU3. For those not running the latest beta versions, I will leave it posted here as it is functionally the same as what was added to file.au3.

[GaryC]

I see an incompatibility between this version of _ArrayBinarySearch and the standard one. The parameter order of the standard version is

Func _ArrayBinarySearch(Const ByRef $avArray, $vValue, $iStart = 0, $iEnd = 0)

Yours is

Func _ArrayBinarySearch(Const ByRef $avArray, $vValue, $iSubItem = 0, $iStart = 0, $iEnd = 0)

If you moved the $iSubItem parameter to the end like this

Func _ArrayBinarySearch(Const ByRef $avArray, $vValue= 0, $iStart = 0, $iEnd = 0, $iSubItem = 0)

it would be more of a "drop-in replacement" for the standard UDF.

I also posted modifications to some of the _array_* functions to add enhancements () which you might want to incorporate.