'**********************************************************************************************************
' Name:                 isInArray
' Author:               mielk | 2011-07-19
'
' Comment:              Checks if a specified value is contained in the given array.
'
' Parameters:
'   value               String to be checked.
'   arr                 Array to be tested.
'                       Each item of this array is compared to source value [value] and if any of them is
'                       equal to this string, function returns True.
'                       Parameter [arr] has to be a one-dimensional array that contains only values of
'                       primitive types. If it contain any object, exception ObjectsInArrayException will
'                       be thrown.
'   isCaseSensitive     Optional parameter of Boolean type.
'                       It determines if text comparing is case sensitive.
'                       If this value is set to True, comparing is case sensitive - a letter in lowercase
'                       is treated as different than the same letter in uppercase (i.e. a ? A).
'                       If this value is set to False, it doesn't matter if a letter is in lowercase or in
'                       uppercase, since both of them are considered as the same character (i.e. a = A).
'                       Default value of this parameter is False.
'
' Returns:
'   Boolean             True - if any item of the given array [arr] is equal to the
'                               specified string [str].
'                       False - otherwise.
'
' Exceptions:
'   NotArrayException               Thrown when the given [arr] parameter is not an array.
'   ObjectsInArrayException         Thrown when the given array contains not only values of primitive
'                                   types, but also objects.
'
'
' --- Changes log -----------------------------------------------------------------------------------------
' 2011-07-19    mielk       Class created.
'**********************************************************************************************************
Public Function isInArray(value As String, arr As Variant, _
                                                    Optional isCaseSensitive As Boolean = False) As Boolean
    Const METHOD_NAME As String = "startsWith"
    Dim SEPARATOR As String: SEPARATOR = VBA.Chr(0)
    '------------------------------------------------------------------------------------------------------
    Dim tempStr As String
    Dim uCompareMethod As VBA.VbCompareMethod
    '------------------------------------------------------------------------------------------------------

    
    'Checks if the given parameter [arr] is an array. If not, code moves to the -------------------------|
    'NotArrayException label.                                                                           '|
    If countDimensions(arr) <> 1 Then GoTo NotArrayException                                            '|
    '----------------------------------------------------------------------------------------------------|


    'Convert [isCaseSensitive] parameter of Boolean type to the [VbCompareMethod] enumeration. ----------|
    If isCaseSensitive Then                                                                             '|
        uCompareMethod = VBA.vbBinaryCompare                                                            '|
    Else                                                                                                '|
        uCompareMethod = VBA.vbTextCompare                                                              '|
    End If                                                                                              '|
    '----------------------------------------------------------------------------------------------------|


    'Try to convert the given array into String using VBA-built-in function Join. If there is -----------|
    'any object in the given array error will be generated and macro moves to the                       '|
    'ObjectsInArrayException label.                                                                     '|
    On Error GoTo ObjectsInArrayException                                                               '|
    tempStr = SEPARATOR & VBA.Join(arr, SEPARATOR) & SEPARATOR                                          '|
    On Error GoTo 0                                                                                     '|
    '----------------------------------------------------------------------------------------------------|


    isInArray = VBA.InStr(1, tempStr, SEPARATOR & value & SEPARATOR, uCompareMethod)


'==========================================================================================================
ExitPoint:
    Exit Function


'-----------------------------------------------
NotArrayException:
    '(...)
    'Put your own error handling here for a case if the given parameter [arr] is not array.
    
    GoTo ExitPoint


ObjectsInArrayException:
    '(...)
    'Put your own error handling here for a case if the given array contains any object.
    
    GoTo ExitPoint


End Function




'**********************************************************************************************************
' Name:         countDimensions
' Author:       mielk | 2012-03-03
'
' Comment:      Returns the number of dimensions of the given VBA array.
'
' Parameters:
'   arr         Array for which number of dimensions is to be returned.
'
' Returns:
'   Integer     The number of dimensions of the given VBA array.
'               If the given value is not an array function returns -1.
'               If the given value is declared as a dynamic array but its dimensions have not been
'               declared yet, 0 is returned.
'
'
' --- Changes log -----------------------------------------------------------------------------------------
' 2012-03-03        mielk       Function created.
' 2014-06-15        mielk       Returned type changed to Integer to allow -1 to be returned.
'                               For non-arrays values -1 is returned.
'**********************************************************************************************************
Public Function countDimensions(arr As Variant) As Integer
    Const METHOD_NAME As String = "countDimensions"
    '------------------------------------------------------------------------------------------------------
    Dim bound As Long
    '------------------------------------------------------------------------------------------------------


    If VBA.IsArray(arr) Then
        
        On Error GoTo NoMoreDimensions
        Do
            bound = UBound(arr, countDimensions + 1)
            countDimensions = countDimensions + 1
        Loop
        
    Else
        
        countDimensions = -1
        
    End If



'----------------------------------------------------------------------------------------------------------
NoMoreDimensions:

End Function