Merge pull request #3 from ECP-Solutions/utf8_encoding_support

ws-garcia · web-flow · commit 0130f89571ad · 2025-04-07T17:46:12.000-04:00
UTF-8 encoding support
diff --git a/README.md b/README.md
@@ -8,6 +8,7 @@ ECPTextStream is an easy-to-use class module developed to enable buffered text s
 ## Advantages
 * The fastest way for I/O operations over "big" text files from VBA (up to 600 MB/sec.).
   ![Benchmark](/docs/home/TextRead-Benchmark.png)
+* [UTF-8](https://www.unicode.org/faq/utf_bom.html#UTF8) encoding support. Do you have a text file, perhaps in chinese or some other foreign cyrillic language, downloaded from the Internet? This library is made to help you deal with it! You will be able to read and write UTF-8 encoded files in an easy way. 
 * Supports files up to 2 GB of size.
 * Supports streams delimited by CRLF, LF and CR characters. This is useful when working with structured files like CSVs.
 * No memory overloads. Text files being read using a buffer, small enough to hold a single data line. 
@@ -33,7 +34,7 @@ Visit [this site](https://ws-garcia.github.io/ECPTextStream/limitations/index.ht
 
 ## License
 
-Copyright (C) 2021-2023  [W. García](https://github.com/ws-garcia/).
+Copyright (C) 2025  [ECP Solutions](https://github.com/ecp-solutions/).
 
 This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
 
diff --git a/docs/api/methods/detectencoding.md b/docs/api/methods/detectencoding.md
@@ -0,0 +1,38 @@
+---
+title: DetectEncoding
+parent: Methods
+grand_parent: API
+nav_order: 2
+---
+
+# DetectEncoding
+{: .fs-9 }
+
+Use heuristics to try to infer the encoding of the target text file.
+{: .fs-6 .fw-300 }
+
+---
+
+## Syntax
+
+*expression*.`DetectEncoding`*(FilePath)*
+
+### Parameters
+
+The required *FilePath* argument is an identifier specifying a `String` type variable.
+
+### Return value
+
+*Type*: `String`
+
+>📝**Note**
+>{: .text-grey-lt-000 .bg-green-000 }
+>The `DetectEncoding` method supports files with or without BOM. the following encodings can be detected: `ANSI`, `UTF-8` and `UTF-16`(BE,LE).
+{: .text-grey-dk-300 .bg-grey-lt-000 }
+
+See also
+: [ReadText Method](https://ecp-solutions.github.io/ECPTextStream/api/methods/readtext.html).
+
+---
+
+[Back to Methods overview](https://ecp-solutions.github.io/VBA-CSV-interface/api/methods/)
diff --git a/docs/api/methods/openstream.md b/docs/api/methods/openstream.md
@@ -2,7 +2,7 @@
 title: OpenStream
 parent: Methods
 grand_parent: API
-nav_order: 2
+nav_order: 3
 ---
 
 # OpenStream
diff --git a/docs/api/methods/readtext.md b/docs/api/methods/readtext.md
@@ -2,7 +2,7 @@
 title: ReadText
 parent: Methods
 grand_parent: API
-nav_order: 3
+nav_order: 4
 ---
 
 # ReadText
diff --git a/docs/api/methods/restartstreamreader.md b/docs/api/methods/restartstreamreader.md
@@ -2,7 +2,7 @@
 title: RestartStreamReader
 parent: Methods
 grand_parent: API
-nav_order: 4
+nav_order: 5
 ---
 
 # RestartStreamReader
diff --git a/docs/api/methods/seekpointer.md b/docs/api/methods/seekpointer.md
@@ -2,7 +2,7 @@
 title: SeekPointer
 parent: Methods
 grand_parent: API
-nav_order: 5
+nav_order: 6
 ---
 
 # SeekPointer
diff --git a/docs/api/methods/writeblanklines.md b/docs/api/methods/writeblanklines.md
@@ -2,7 +2,7 @@
 title: WriteBlankLines
 parent: Methods
 grand_parent: API
-nav_order: 6
+nav_order: 7
 ---
 
 # WriteBlankLines
diff --git a/docs/api/methods/writetext.md b/docs/api/methods/writetext.md
@@ -2,7 +2,7 @@
 title: WriteText
 parent: Methods
 grand_parent: API
-nav_order: 7
+nav_order: 8
 ---
 
 # WriteText
diff --git a/docs/api/properties/autodetectencoding .md b/docs/api/properties/autodetectencoding .md
@@ -0,0 +1,49 @@
+---
+title: autoDetectEncoding
+parent: Properties
+grand_parent: API
+nav_order: 2
+---
+
+# autoDetectEncoding
+{: .fs-9 }
+
+Defines whether the tool should attempt to automatically infer the file encoding.
+{: .fs-6 .fw-300 }
+
+---
+
+## ReadWrite
+
+_Yes_
+
+---
+
+## Syntax
+
+|**_Accesor_**|**_Syntax_**|
+|:----------|:----------|
+|Get|*expression*.`autoDetectEncoding`|
+|Let|*expression*.`autoDetectEncoding` = value|
+
+|**_Accesor_**|**_Parameters_**|
+|:----------|:----------|
+|Get|_None_|
+|Let|*Name*: Value<br>*Type*: `Boolean`<br>*Modifiers*: `ByVal`|
+
+|**_Accesor_**|**_Returns Type_**|
+|:----------|:----------|
+|Get|`Boolean`|
+|Let|_None_|
+
+>📝**Note**
+>{: .text-grey-lt-000 .bg-green-000 }
+>At the moment the tool can detect the following encodings: `ANSI`, `UTF-8` and `UTF-16`(BE,LE).
+{: .text-grey-dk-300 .bg-grey-lt-000 }
+
+See also
+: [ReadText Method](https://ecp-solutions.github.io/ECPTextStream/api/methods/readtext.html).
+
+---
+
+[Back to Properties overview](https://ecp-solutions.github.io/ECPTextStream/api/properties/)
diff --git a/docs/api/properties/bufferlength.md b/docs/api/properties/bufferlength.md
@@ -2,7 +2,7 @@
 title: bufferLength
 parent: Properties
 grand_parent: API
-nav_order: 2
+nav_order: 3
 ---
 
 # bufferLength
diff --git a/docs/api/properties/buffersize.md b/docs/api/properties/buffersize.md
@@ -2,7 +2,7 @@
 title: bufferSize
 parent: Properties
 grand_parent: API
-nav_order: 3
+nav_order: 4
 ---
 
 # bufferSize
diff --git a/docs/api/properties/bufferstring.md b/docs/api/properties/bufferstring.md
@@ -2,7 +2,7 @@
 title: bufferString
 parent: Properties
 grand_parent: API
-nav_order: 4
+nav_order: 5
 ---
 
 # bufferString
diff --git a/docs/api/properties/detectedencoding.md b/docs/api/properties/detectedencoding.md
@@ -0,0 +1,44 @@
+---
+title: detectedEncoding
+parent: Properties
+grand_parent: API
+nav_order: 6
+---
+
+# detectedEncoding
+{: .fs-9 }
+
+Returns the name of the encoding detected in the file.
+{: .fs-6 .fw-300 }
+
+---
+
+## ReadWrite
+
+_ReadOnly_
+
+---
+
+## Syntax
+
+*expression*.`detectedEncoding`
+
+### Parameters
+
+_None_
+
+### Returns
+
+*Type*: `String`
+
+>📝**Note**
+>{: .text-grey-lt-000 .bg-green-000 }
+>At the moment the tool can detect the following encodings: `ANSI`, `UTF-8` and `UTF-16`(BE,LE).
+{: .text-grey-dk-300 .bg-grey-lt-000 }
+
+See also
+: [ReadText Method](https://ecp-solutions.github.io/ECPTextStream/api/methods/readtext.html).
+
+---
+
+[Back to Properties overview](https://ecp-solutions.github.io/ECPTextStream/api/properties/)
diff --git a/docs/api/properties/endstreamonlinebreak.md b/docs/api/properties/endstreamonlinebreak.md
@@ -2,7 +2,7 @@
 title: endStreamOnLineBreak
 parent: Properties
 grand_parent: API
-nav_order: 5
+nav_order: 7
 ---
 
 # endStreamOnLineBreak
@@ -36,6 +36,11 @@ _Yes_
 |Get|`Boolean`|
 |Let|_None_|
 
+>📝**Note**
+>{: .text-grey-lt-000 .bg-green-000 }
+>It is recommended to set this property to `True` when working with non-ANSI encoded files.
+{: .text-grey-dk-300 .bg-grey-lt-000 }
+
 See also
 : [ReadText Method](https://ecp-solutions.github.io/ECPTextStream/api/methods/readtext.html).
  
diff --git a/docs/api/properties/isopenstream.md b/docs/api/properties/isopenstream.md
@@ -2,7 +2,7 @@
 title: isOpenStream
 parent: Properties
 grand_parent: API
-nav_order: 6
+nav_order: 8
 ---
 
 # isOpenStream
diff --git a/docs/api/properties/linebreak.md b/docs/api/properties/linebreak.md
@@ -2,7 +2,7 @@
 title: lineBreak
 parent: Properties
 grand_parent: API
-nav_order: 7
+nav_order: 9
 ---
 
 # lineBreak
diff --git a/docs/api/properties/linebreakmatchingbehavior.md b/docs/api/properties/linebreakmatchingbehavior.md
@@ -2,7 +2,7 @@
 title: linebreakMatchingBehavior
 parent: Properties
 grand_parent: API
-nav_order: 8
+nav_order: 10
 ---
 
 # linebreakMatchingBehavior
diff --git a/docs/api/properties/pointerposition.md b/docs/api/properties/pointerposition.md
@@ -2,7 +2,7 @@
 title: pointerPosition
 parent: Properties
 grand_parent: API
-nav_order: 9
+nav_order: 11
 ---
 
 # pointerPosition
diff --git a/docs/api/properties/streamlength.md b/docs/api/properties/streamlength.md
@@ -2,7 +2,7 @@
 title: streamLength
 parent: Properties
 grand_parent: API
-nav_order: 10
+nav_order: 12
 ---
 
 # streamLength
diff --git a/docs/api/properties/unifiedlfoutput.md b/docs/api/properties/unifiedlfoutput.md
@@ -2,7 +2,7 @@
 title: unifiedLFOutput
 parent: Properties
 grand_parent: API
-nav_order: 11
+nav_order: 13
 ---
 
 # unifiedLFOutput
diff --git a/docs/home/getting_started.md b/docs/home/getting_started.md
@@ -67,11 +67,11 @@ Sub StreamAndSave()
     Path = "C:\6400000.quoted.csv"
     Set TextStream = New ECPTextStream
     TextStream.OpenStream Path
-    TextStream.EndStreamOnLineBreak = True
-    ReDim tmpArray(0 To Fix(TextStream.StreamLength / TextStream.BufferLen) + 1)
-    Do While Not TextStream.AtEndOfStream
+    TextStream.endStreamOnLineBreak = True
+    ReDim tmpArray(0 To Fix(TextStream.streamLength / TextStream.bufferLength) + 1)
+    Do While Not TextStream.atEndOfStream
         TextStream.ReadText
-        tmpArray(i) = TextStream.BufferString
+        tmpArray(i) = TextStream.bufferString
         i = i + 1
     Loop
     TextStream.CloseStream
diff --git a/docs/index.md b/docs/index.md
@@ -15,6 +15,7 @@ ECPTextStream is an easy-to-use class module developed to enable I/O operations
 ## Advantages
 
 * The fastest way for I/O operations over "big" text files from VBA (up to 600 MB/sec.).
+* [UTF-8](https://www.unicode.org/faq/utf_bom.html#UTF8) encoding support. Do you have a text file, perhaps in chinese or some other foreign cyrillic language, downloaded from the Internet? This library is made to help you deal with it! You will be able to read and write UTF-8 encoded files in an easy way. 
 * Supports files up to 2 GB of size.
 * Supports CRLF, LF and CR as end of each single stream. This is useful when working with structured files like CSVs.
 * No memory overloads. Text files being read with buffer.
diff --git a/src/ECPArrayList.cls b/src/ECPArrayList.cls
diff --git a/src/ECPTextStream.cls b/src/ECPTextStream.cls
