Improvements

Added support for UTF-8 encoded files. Fixed infinite loop when not linebreak found.

Author: ws-garcia

src/ECPTextStream.cls

@@ -9,14 +9,15 @@ Attribute VB_PredeclaredId = False
 Attribute VB_Exposed = False
 '#
 '////////////////////////////////////////////////////////////////////////////////////////////
-' Copyright © 2021 W. García
+' Copyright © 2021-2022 W. García
 ' GPL-3.0 license | https://www.gnu.org/licenses/gpl-3.0.html/
 ' https://ingwilfredogarcia.wordpress.com
 '#
 '////////////////////////////////////////////////////////////////////////////////////////////
 ' GENERAL INFO:
 ' ECPTextStream is an easy-to-use class module developed to enable I/O operations over "big"
-' text files, at high speed, from VBA. The module hasn’t reference to any external API library.
+' text files, at high speed, from VBA. The module hasn’t reference to any external API
+' library and has the ability to read and write UTF-8 encoded files.
 '////////////////////////////////////////////////////////////////////////////////////////////
 '#
 Option Explicit
@@ -25,7 +26,7 @@ Option Explicit
 ' CONSTANTS:
 Private Const DualLFchar As String = vbLf & vbLf
 Private Const InverseCRLF As String = vbLf & vbCr
-Private Const SizeFactor As Long = 524288
+Private Const sizeFactor As Long = 524288
 Private Const WhiteSpace As String = " "
 '////////////////////////////////////////////////////////////////////////////////////////////
 '#
@@ -38,10 +39,12 @@ Private P_ENDSTREAMONLINEBREAK As Boolean '--------If true, each stream ends on
 Private P_ISOPENSTREAM As Boolean '----------------Indicates if the object is linked to a file
 Private P_LINEBREAK As String '--------------------Holds the char used to end a Stream.
 Private P_LINEBREAKMATCHINGBEHAVIOR As EndLineMatchingBehavior 'How to find the next line break.
-Private P_UNIFIEDLFOUTPUT As Boolean '-------------If true, the buffer string will be returned
-'                                                  with the LF char as Line Break.
+Private P_UNIFIEDLFOUTPUT As Boolean '-------------If true, the buffer string will be returned _
+                                                   with the LF char as Line Break.
 Private P_STREAMLENGTH As Long '-------------------File len.
 Private P_TEXT As String '-------------------------Holds the current stream's text.
+Private P_UTF8ENCODED As Boolean '-----------------Indicates when the file is supposed to be _
+                                                   UTF8 encoded.
 '////////////////////////////////////////////////////////////////////////////////////////////
 '#
 '////////////////////////////////////////////////////////////////////////////////////////////
@@ -93,15 +96,19 @@ Attribute bufferSize.VB_Description = "Gets or sets the buffer
 End Property
 Public Property Let bufferSize(value As Single)
     P_BUFFERSIZE = value
-    P_BUFFERLENGTH = CLng(P_BUFFERSIZE * SizeFactor)
+    P_BUFFERLENGTH = CLng(P_BUFFERSIZE * sizeFactor)
     Buffer = SPACE$(P_BUFFERLENGTH)
 End Property
 Public Property Get bufferString() As String
 Attribute bufferString.VB_Description = "Gets the text data stored in the buffer."
     If P_UNIFIEDLFOUTPUT Then
         NormalizeLineBreaks
     End If
-    bufferString = P_TEXT
+    If Not P_UTF8ENCODED Then
+        bufferString = P_TEXT
+    Else
+        bufferString = UTF8Decode(P_TEXT)
+    End If
 End Property
 Public Property Get endStreamOnLineBreak() As Boolean
 Attribute endStreamOnLineBreak.VB_Description = "Allows to end buffer just after the first, from right to left, line break character."
@@ -113,9 +120,9 @@ End Property
 Public Property Get isOpenStream() As Boolean
     isOpenStream = P_ISOPENSTREAM
 End Property
-Public Property Get lineBreak() As String
-Attribute lineBreak.VB_Description = "Returns the character used to end the last received stream. The value is vbNullString when the last stream is not forced to end on line break."
-    lineBreak = P_LINEBREAK
+Public Property Get LineBreak() As String
+Attribute LineBreak.VB_Description = "Returns the character used to end the last received stream. The value is vbNullString when the last stream is not forced to end on line break."
+    LineBreak = P_LINEBREAK
 End Property
 Public Property Get linebreakMatchingBehavior() As EndLineMatchingBehavior
     linebreakMatchingBehavior = P_LINEBREAKMATCHINGBEHAVIOR
@@ -136,12 +143,19 @@ Attribute streamLength.VB_Description = "Gets the current opened file
     streamLength = P_STREAMLENGTH
 End Property
 Public Property Get unifiedLFOutput() As Boolean
-Attribute unifiedLFOutput.VB_Description = "Determines whether the buffer string is returned using only the LF character as a linefeed."
+Attribute unifiedLFOutput.VB_Description = "Determines whether the buffer string is returned using only the LF character as a line feed. Similarly, this property instruct to write files without the Unicode Byte Order Mark."
     unifiedLFOutput = P_UNIFIEDLFOUTPUT
 End Property
 Public Property Let unifiedLFOutput(value As Boolean)
     P_UNIFIEDLFOUTPUT = value
 End Property
+Public Property Get utf8EncodedFile() As Boolean
+Attribute utf8EncodedFile.VB_Description = "Indicates whether the buffer string is returned as a decoded string, assuming the file is UTF8 encoded."
+    utf8EncodedFile = P_UTF8ENCODED
+End Property
+Public Property Let utf8EncodedFile(value As Boolean)
+    P_UTF8ENCODED = value
+End Property
 '////////////////////////////////////////////////////////////////////////////////////////////
 '#
 '////////////////////////////////////////////////////////////////////////////////////////////
@@ -156,7 +170,7 @@ End Sub
 Private Sub DoubleBufferSize()
     Dim LCSt As Long
     P_BUFFERSIZE = 2 * P_BUFFERSIZE
-    P_BUFFERLENGTH = CLng(P_BUFFERSIZE * SizeFactor)
+    P_BUFFERLENGTH = CLng(P_BUFFERSIZE * sizeFactor)
     LCSt = P_STREAMLENGTH - P_BUFFERLENGTH
     Select Case LCSt
         Case Is > 0
@@ -318,44 +332,82 @@ Attribute SeekPointer.VB_Description = "Moves the pointer, over the target file,
 End Sub
 Private Sub StartVariables()
     CorrectedPos = 0
-    P_BUFFERLENGTH = CLng(P_BUFFERSIZE * SizeFactor)
+    P_BUFFERLENGTH = CLng(P_BUFFERSIZE * sizeFactor)
     Buffer = SPACE$(P_BUFFERLENGTH)
     LCS = P_STREAMLENGTH
     P_ATENDOFSTREAM = False
 End Sub
+Public Function UTF8Decode(ByVal sStr As String) As String
+    Dim l As Long, sUTF8 As CSVArrayList, iChar As Long, iChar2 As Long
+    
+    On Error GoTo UTF8_Decode_error
+    Set sUTF8 = New CSVArrayList
+    For l = 1 To LenB(sStr) Step 2
+        iChar = Asc(MidB$(sStr, l, 2))
+        If iChar > 127 Then
+            If Not iChar And 32 Then ' 2 chars
+                iChar2 = Asc(MidB$(sStr, l + 2, 2))
+                sUTF8.Add ChrW$(((31 And iChar) * 64 + (63 And iChar2)))
+                l = l + 2
+            Else
+                Dim iChar3 As Integer
+                iChar2 = Asc(MidB$(sStr, l + 2, 2))
+                iChar3 = Asc(MidB$(sStr, l + 4, 2))
+                sUTF8.Add ChrW$(((iChar And 15) * 16 * 256) + ((iChar2 And 63) * 64) + (iChar3 And 63))
+                l = l + 4
+            End If
+        Else
+            sUTF8.Add ChrW$(iChar)
+        End If
+    Next l
+    UTF8Decode = Join$(sUTF8.items, vbNullString)
+    Set sUTF8 = Nothing
+    Exit Function
+UTF8_Decode_error:
+    Set sUTF8 = Nothing
+    UTF8Decode = vbNullString
+End Function
 Public Sub WriteBlankLines(Lines As Long, Optional EndLineMark As EndLineChar = 0)
 Attribute WriteBlankLines.VB_Description = "Inserts a specified number of blank lines into the current opened text file."
     If P_ISOPENSTREAM Then
-        Dim idx As Long
+        Dim Idx As Long
         Select Case EndLineMark
             Case 0
-                For idx = 1 To Lines
-                    Put #FileHandled, , vbCrLf
-                Next idx
+                For Idx = 1 To Lines
+                    WriteText vbCrLf
+                Next Idx
             Case 1
-                For idx = 1 To Lines
-                    Put #FileHandled, , vbCr
-                Next idx
+                For Idx = 1 To Lines
+                    WriteText vbCr
+                Next Idx
             Case 2
-                For idx = 1 To Lines
-                    Put #FileHandled, , vbLf
-                Next idx
+                For Idx = 1 To Lines
+                    WriteText vbLf
+                Next Idx
         End Select
         P_STREAMLENGTH = LOF(FileHandled)
     End If
 End Sub
 Public Sub WriteText(ByRef TextData As String)
 Attribute WriteText.VB_Description = "Writes the given string to the current opened text file."
     If P_ISOPENSTREAM Then
-        Put #FileHandled, , TextData
+        If Not P_UTF8ENCODED Then
+            Put #FileHandled, , TextData
+        Else
+            Dim BuffferBytes() As Byte
+            BuffferBytes = TextData
+            Put #FileHandled, , BuffferBytes
+            Erase BuffferBytes
+        End If
         P_STREAMLENGTH = LOF(FileHandled)
     End If
 End Sub
 '////////////////////////////////////////////////////////////////////////////////////////////
 Private Sub Class_Initialize()
     P_BUFFERSIZE = 0.5
-    P_BUFFERLENGTH = CLng(P_BUFFERSIZE * SizeFactor)
+    P_BUFFERLENGTH = CLng(P_BUFFERSIZE * sizeFactor)
     P_ENDSTREAMONLINEBREAK = False
+    P_UTF8ENCODED = False
     P_LINEBREAKMATCHINGBEHAVIOR = EndLineMatchingBehavior.Bidirectional
     P_UNIFIEDLFOUTPUT = False
     Buffer = SPACE$(P_BUFFERLENGTH)