Merge pull request #6 from ws-garcia/dump-data-to-sheet-method

Add DumpToSheet method, update docs repo

Author: ws-garcia

docs/api/methods/dumptoarray.md

@@ -29,19 +29,19 @@ _None_
 
 ## Remarks
 
-**Note**: *Before dump data, is recommended to make a `ImportFromCSV` method call.*
+**Note**: *Before dump data, is recommended to make a `ImportFromCSV` or `ImportFromCSVstring` method call.*
 
 The *OutPutArray* parameter must be declared as dynamic `String` array. If user forget to do this, an error will occur.
 
 See also
-: [ImportFromCSV method](https://ws-garcia.github.io/VBA-CSV-interface/api/methods/importfromcsv.html).
+: [ImportFromCSV method](https://ws-garcia.github.io/VBA-CSV-interface/api/methods/importfromcsv.html), [ImportFromCSVstring method](https://ws-garcia.github.io/VBA-CSV-interface/api/methods/importfromcsvstring.html).
 
 ---
 
 ## Behavior
 
 The `DumpToArray` method make a copy of all the data stored in the current instance. The data is returned in the *OutPutArray* parameter for avoid additional data copies in the internals.
 
-The dumped data will be erased from memory, in other words, the current instance doesn't hold the CSV read data any more. In the same way, the `DumpToArray` method returns an empty `String` array for subsequent calls not preceded by `ImportFromCSV` method call.
+The dumped data will be erased from memory, in other words, the current instance doesn't hold the CSV read data any more. In the same way, the `DumpToArray` method returns an empty `String` array for subsequent calls not preceded by `ImportFromCSV` or or `ImportFromCSVstring` method call.
 
 [Back to Methods overview](https://ws-garcia.github.io/VBA-CSV-interface/api/methods/)

docs/api/methods/dumptosheet.md

@@ -0,0 +1,64 @@
+---
+title: DumpToSheet
+parent: Methods
+grand_parent: API
+nav_order: 2
+---
+
+# DumpToSheet
+{: .fs-9 }
+
+Dumps the data from the current instance to an Excel WorkSheet.
+{: .fs-6 .fw-300 }
+
+---
+
+## Syntax
+
+*expression*.`DumpToSheet`*({WBookName}, {SheetName}, {RngName})*
+
+### Parameters
+
+<table>
+<thead>
+<tr>
+<th style="text-align: left;">Part</th>
+<th style="text-align: left;">Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td style="text-align: left;"><em>WBookName</em></td>
+<td style="text-align: left;">Optional. Identifier specifying a <code>String</code> variable representing the output Workbook name.</td>
+</tr>
+<tr>
+<td style="text-align: left;"><em>SheetName</em></td>
+<td style="text-align: left;">Optional. Identifier specifying a <code>String</code> variable representing the output Worksheet name.</td>
+</tr>
+<tr>
+<td style="text-align: left;"><em>RngName</em></td>
+<td style="text-align: left;">Optional. Identifier specifying a <code>String</code> variable representing the name of the output top left-most range.</td>
+</tr>
+</tbody>
+</table>
+
+### Return value
+
+_None_
+
+---
+
+## Remarks
+
+**Note**: *Before dump data, is recommended to make a `ImportFromCSV` or `ImportFromCSVstring` method call.*
+
+See also
+: [ImportFromCSV method](https://ws-garcia.github.io/VBA-CSV-interface/api/methods/importfromcsv.html), [ImportFromCSVstring method](https://ws-garcia.github.io/VBA-CSV-interface/api/methods/importfromcsvstring.html).
+
+---
+
+## Behavior
+
+When the *WBookName* parameter is omitted the data is dumped into the Workbook that holds the CSV interface's *VBAProject*. Omitting the *SheetName* parameter adds a new Worksheet to the desired Workbook. Also, if the *RngName* parameter is omitted the data will dumped starting on the "A1" named cell in the desired Worksheet.
+
+[Back to Methods overview](https://ws-garcia.github.io/VBA-CSV-interface/api/methods/)

docs/api/methods/exporttocsv.md

@@ -2,7 +2,7 @@
 title: ExportToCSV
 parent: Methods
 grand_parent: API
-nav_order: 2
+nav_order: 3
 ---
 
 # ExportToCSV

docs/api/methods/getdatafromcsv.md

@@ -2,7 +2,7 @@
 title: GetDataFromCSV
 parent: Methods
 grand_parent: API
-nav_order: 3
+nav_order: 4
 ---
 
 # GetDataFromCSV

docs/api/methods/importfromcsv.md

@@ -2,7 +2,7 @@
 title: ImportFromCSV
 parent: Methods
 grand_parent: API
-nav_order: 4
+nav_order: 5
 ---
 
 # ImportFromCSV

docs/api/methods/importfromcsvstring.md

@@ -2,7 +2,7 @@
 title: ImportFromCSVstring
 parent: Methods
 grand_parent: API
-nav_order: 5
+nav_order: 6
 ---
 
 # ImportFromCSVstring

docs/api/methods/openconnection.md

@@ -2,7 +2,7 @@
 title: OpenConnection
 parent: Methods
 grand_parent: API
-nav_order: 6
+nav_order: 7
 ---
 
 # OpenConnection

docs/api/methods/resettodefault.md

@@ -2,7 +2,7 @@
 title: ResetToDefault
 parent: Methods
 grand_parent: API
-nav_order: 7
+nav_order: 8
 ---
 
 # ResetToDefault

src/CSVinterface.cls

@@ -33,7 +33,7 @@ Attribute VB_Exposed = False
 '#
 ' Use CSVinterface class to simplify the work with comma separated value (CSV) files.
 ' It allow you to exchange information betwen an VBA array and an external CSV file without
-' using Excel WorkSheets, neigter any external reference such as [MS Scripting Runtime].
+' using Excel Worksheets, neigter any external reference such as [MS Scripting Runtime].
 ' The class develop is focusing in the code execution performance.
 '#
 ' Feel free to visit the cited websites to explore some of the available solutions for
@@ -60,13 +60,14 @@ Attribute VB_Exposed = False
 ' @1 https://senipah.github.io/VBA-Better-Array
 ' @2 https://github.com/sdkn104/VBA-CSV
 ' @3 http://www.vbaexpress.com/forum/showthread.php?25095-Solved-Check-the-file-encode-type
-' @4 https://www.codegrepper.com/code-examples/vb/excel+vba+Load+csv+file+into+an+array+rather+than+the+worksheet
+' @4 https://www.codegrepper.com/code-examples/vb/excel+vba+Load+csv+file+into+an+array+rather+than+the+Worksheet
 ' @5 http://excellerando.blogspot.com/2014/12/writing-excel-range-to-csv-file.html
 ' @6 https://stackoverflow.com/questions/4191560/create-csv-from-array-in-vba
 ' @7 https://www.freevbcode.com/ShowCode.asp?ID=3110
 ' @8 https://stackoverflow.com/questions/1376756/what-is-a-superfast-way-to-read-large-files-line-by-line-in-vba
 ' @9 https://www.freevbcode.com/ShowCode.asp?ID=7655
-
+' @10 http://www.cpearson.com/excel/mainpage.aspx
+' @11 https://www.exceltip.com/excel-macros-and-vba
 '////////////////////////////////////////////////////////////////////////////////////////////
 '#
 Option Explicit
@@ -293,6 +294,63 @@ Attribute DumpToArray.VB_UserMemId = 0
     OutPutArray() = P_CSV_DATA
     Erase P_CSV_DATA
 End Sub
+Public Sub DumpToSheet(Optional WBookName As String, _
+                        Optional SheetName As String, _
+                        Optional RngName As String = "A1")
+Attribute DumpToSheet.VB_Description = "Dumps the CSV data from the current instance to an Excel Worksheet."
+    Dim WBook As Workbook
+    Dim OutputSheet As Worksheet
+    Dim OutputRange As Range
+    
+    On Error Resume Next
+    If IsArrayAllocated(P_CSV_DATA) Then
+        EnableOptimization
+        '@------------------------------------------------------
+        'Set the target Workbook
+        If WBookName = vbNullString Then
+            Set WBook = ThisWorkbook
+        ElseIf Not IsWorkbookOpen(WBookName) Then
+            Set WBook = Workbooks.Add
+        Else
+            Set WBook = Workbooks(WBookName)
+        End If
+        '@------------------------------------------------------
+        'Set the target Worksheet
+        If IsSheetInWorkbook(SheetName, WBook) Then
+            Set OutputSheet = WBook.Sheets(SheetName)
+        Else
+            Set OutputSheet = WBook.Sheets.Add
+        End If
+        '@------------------------------------------------------
+        'Set the target Range
+        Set OutputRange = OutputSheet.Range(RngName) _
+                            .Resize _
+                            ( _
+                            UBound(P_CSV_DATA, 1) - LBound(P_CSV_DATA, 1) + 1, _
+                            UBound(P_CSV_DATA, 2) - LBound(P_CSV_DATA, 2) + 1 _
+                            )
+        '@------------------------------------------------------
+        'Dump the data
+        OutputRange.Value2 = P_CSV_DATA
+        EnableOptimization False
+    End If
+End Sub
+Private Sub EnableOptimization(Optional Optimize As Boolean = True)
+Attribute EnableOptimization.VB_Description = "Turn On and Off the optimized data dumping to an Excel Worksheet."
+    If Optimize Then
+        '@------------------------------------------------------
+        'Optimize resource consumption
+        Application.ScreenUpdating = False
+        Application.Calculation = xlCalculationManual
+        Application.EnableEvents = False
+    Else
+        '@------------------------------------------------------
+        'Turn Off optimization
+        Application.ScreenUpdating = True
+        Application.Calculation = xlCalculationAutomatic
+        Application.EnableEvents = True
+    End If
+End Sub
 Public Sub ExportToCSV(csvArray As Variant)
 Attribute ExportToCSV.VB_Description = "Exports a 2D array to a CSV file located in the path specified in the OpenConnection method."
     On Error GoTo ErrHandler_ExportToCSV
@@ -597,6 +655,36 @@ Attribute IsANSI.VB_Description = "Verifies the charset for ANSI encoding."
     Erase bytFile
     IsANSI = (lngIndx > lngUprBnd)
 End Function
+Private Function IsArrayAllocated(ByRef arr() As String) As Boolean
+Attribute IsArrayAllocated.VB_Description = "Verifies if the given array is allocated on memory."
+    Dim N As Long
+
+    On Error Resume Next
+    N = UBound(arr, 1)
+    If Err.number = 0 Then
+        IsArrayAllocated = True
+    Else
+        IsArrayAllocated = False
+    End If
+End Function
+Private Function IsSheetInWorkbook(SheetName As String, WBook As Workbook) As Boolean
+Attribute IsSheetInWorkbook.VB_Description = "Checks if the given sheet is part of the given or of the active one Workbook."
+    With WBook
+        On Error Resume Next
+        IsSheetInWorkbook = (.Sheets(SheetName).Name = SheetName)
+        On Error GoTo 0
+    End With
+End Function
+Private Function IsWorkbookOpen(WBookName As String) As Boolean
+Attribute IsWorkbookOpen.VB_Description = "Checks if the given Workbook is opened yet."
+    Dim WBook As Workbook, BookMatching As Boolean
+    
+    On Error Resume Next
+    For Each WBook In Workbooks
+        BookMatching = (WBook.Name = WBookName)
+    Next
+    IsWorkbookOpen = BookMatching
+End Function
 Private Function JoinRecordsFields(RecordsArray As Variant) As String
 Attribute JoinRecordsFields.VB_Description = "Joins all fields for each record in the specified array."
     Dim buffer() As String