'**********************************************************************************************************
' Name:                 dictionaryToArray
' Author:               mielk | 2013-04-10
'
' Comment:              Convert the given dictionary into two-dimensional array.
'                       Result array can contain values only, keys only or both, depending on the given
'                       optional parameters includeKeys and includeValues.
'
' Parameters:
'   dict                Dictionary to be converted into an array.
'   includeKeys         Optional parameter determining if keys are to be included in the result array.
'                       Default value of this parameter is True.
'   includeValues       Optional parameter determining if values are to be included in the result array.
'                       Default value of this parameter is True.
'
' Returns:
'   Variant()           Array of the keys and values from the given dictionary.
'
'
' Exceptions:
'   IllegalTypeException            Thrown if the given parameter is not a dictionary.
'   IllegalParameters               Thrown if both parameters (includeKeys and includeValues) are set to
'                                   False.
'
'
' --- Changes log -----------------------------------------------------------------------------------------
' 2013-04-10        mielk           Function created.
'**********************************************************************************************************
Public Function dictionaryToArray(dict As Variant, Optional includeKeys As Boolean = True, _
                                                   Optional includeValues As Boolean = True) As Variant()
    Const METHOD_NAME As String = "dictionaryToArray"
    '------------------------------------------------------------------------------------------------------
    Const ARRAY_BASE_INDEX As Long = 0
    Const DICTIONARY_TYPENAME As String = "Dictionary"
    '------------------------------------------------------------------------------------------------------
    Dim varKey As Variant
    Dim arr() As Variant
    Dim lngItem As Long
    Dim columns As Integer
    '------------------------------------------------------------------------------------------------------
    
    
    'Check if the given parameter dict is a dictionary. -------------------------------------------------|
    If VBA.StrComp(VBA.TypeName(dict), DICTIONARY_TYPENAME, vbTextCompare) Then _
                                                                            GoTo IllegalTypeException   '|
    '----------------------------------------------------------------------------------------------------|
    
    
    'Check if at least one parameter from [includeKeys], [includeValues] is set to True. Otherwise, -----|
    'there is no point to continue with this function, since user selected no data to be included.      '|
    If Not includeKeys And Not includeValues Then GoTo IllegalParameters                                '|
    columns = VBA.IIf(includeKeys, 1, 0) + VBA.IIf(includeValues, 1, 0)                                 '|
    '----------------------------------------------------------------------------------------------------|
    
    
    'If the given dictionary is empty, empty array will be returned. ------------------------------------|
    If dict.Count Then                                                                                  '|
                                                                                                        '|
        'Resize final table [arr] to be big enough for all the items from the given dictionary. -----|  '|
        ReDim arr(1 To columns, 1 To dict.Count)                                                    '|  '|
        For Each varKey In dict.keys                                                                '|  '|
            lngItem = lngItem + 1                                                                   '|  '|
                                                                                                    '|  '|
            'Appending keys to the final array (if applicable). ---------------------------------|  '|  '|
            If includeKeys Then                                                                 '|  '|  '|
                                                                                                '|  '|  '|
                'Before adding value to the result array check if it is an object or --------|  '|  '|  '|
                'a primitive value and apply proper action.                                 '|  '|  '|  '|
                If VBA.IsObject(varKey) Then                                                '|  '|  '|  '|
                    Set arr(1, lngItem) = varKey                                            '|  '|  '|  '|
                Else                                                                        '|  '|  '|  '|
                    arr(1, lngItem) = varKey                                                '|  '|  '|  '|
                End If                                                                      '|  '|  '|  '|
                '----------------------------------------------------------------------------|  '|  '|  '|
                                                                                                '|  '|  '|
            End If                                                                              '|  '|  '|
            '------------------------------------------------------------------------------------|  '|  '|
                                                                                                    '|  '|
                                                                                                    '|  '|
            'Appending values to the final array (if applicable). -------------------------------|  '|  '|
            If includeValues Then                                                               '|  '|  '|
                                                                                                '|  '|  '|
                'Before adding value to the result array check if it is an object or --------|  '|  '|  '|
                'a primitive value and apply proper action.                                 '|  '|  '|  '|
                If VBA.IsObject(varKey) Then                                                '|  '|  '|  '|
                    Set arr(columns, lngItem) = varKey                                      '|  '|  '|  '|
                Else                                                                        '|  '|  '|  '|
                    arr(columns, lngItem) = varKey                                          '|  '|  '|  '|
                End If                                                                      '|  '|  '|  '|
                '----------------------------------------------------------------------------|  '|  '|  '|
                                                                                                '|  '|  '|
            End If                                                                              '|  '|  '|
            '------------------------------------------------------------------------------------|  '|  '|
                                                                                                    '|  '|
        Next varKey                                                                                 '|  '|
        '--------------------------------------------------------------------------------------------|  '|
                                                                                                        '|
    End If                                                                                              '|
    '----------------------------------------------------------------------------------------------------|
    
    
    
    'Assign the final table to the result variable.
    dictionaryToArray = arr
    
    
    
'==========================================================================================================
ExitPoint:
    Exit Function

'----------------------------------------------------------------------------------------------------------
IllegalTypeException:
    'Error handling for the case if the given parameter is not a dictionary.
    
    GoTo ExitPoint


IllegalParameters:
    'Error handling for the case if both parameters - includeKeys and includeValues - are set to False.
    
    GoTo ExitPoint


End Function