What the Class Is Used For

Use Chilkat.StringTable when an application needs a lightweight list of strings, especially when the data is naturally represented as one string per line. It is useful for word lists, pattern lists, exclusion lists, parsed delimited values, line-oriented files, and simple string lookup workflows.

Build a String List Add individual strings with Append, or load many strings from a file or StringBuilder.

Search the Table Find strings containing a substring, or match text against wildcard patterns stored in the table.

Sort and Retrieve Sort strings ascending or descending, then retrieve values by zero-based index.

Import and Export Lines Read one line per string from a file and write the table back using chosen line endings and character encoding.

Typical Workflow

Create a StringTable object.
Add strings with Append, AppendFromFile, AppendFromSb, or SplitAndAppend.
Use Count to determine how many strings are present.
Retrieve strings with StringAt or StringAtSb.
Search with FindSubstring, FindMatch, or WordFollowing.
Optionally sort with Sort.
Export the table with GetStrings, ToSb, or SaveToFile.
Use Clear to remove all strings.
Check LastErrorText if an operation fails or behaves unexpectedly.

Core Concepts

Concept	Meaning	Important Members
Ordered String Collection	Strings are stored in a table and retrieved by zero-based index.	Append, StringAt, StringAtSb, Count
Line-Oriented Import	A file or StringBuilder can be appended as one string per line.	AppendFromFile, AppendFromSb
Delimited Splitting	A single input string can be split into table entries using a one-character delimiter.	SplitAndAppend
Searching	The table can be searched by substring or wildcard pattern match.	FindSubstring, FindMatch
Line-Oriented Export	The table can be emitted as text with one string per line.	GetStrings, ToSb, SaveToFile

Properties

Property	Purpose	Guidance
Count	Returns the number of strings in the table.	Use before iterating by index or to determine whether the table is empty.
LastErrorText	Diagnostic information for the last method or property access.	Check after failures or unexpected behavior. Diagnostic information may be available regardless of success or failure.

Adding Strings

Method	Input	Behavior
Append	Single string	Appends one string to the end of the table.
AppendFromFile	Text file	Appends strings from a file, one per line. The charset specifies the file encoding, and maxLineLen specifies the maximum expected line length.
AppendFromSb	StringBuilder	Appends strings from the contents of a StringBuilder, one per line.
SplitAndAppend	Delimited string	Splits a string into parts based on a single-character delimiter and appends the parts to the table.

Line-oriented design: AppendFromFile and AppendFromSb treat each line as one string table entry.

Splitting Strings

SplitAndAppend Option	Meaning	Use When
delimiterChar	A single character used as the delimiter.	Use for comma-separated, pipe-separated, tab-separated, or similar simple delimited strings.
exceptDoubleQuoted	If true, delimiters inside double quotes are ignored.	Use when quoted fields may contain the delimiter character.
exceptEscaped	If true, a delimiter escaped with a backslash is ignored.	Use when the delimiter can appear literally as an escaped character.

Delimiter note: SplitAndAppend splits on a single delimiter character, not a multi-character delimiter string.

Retrieving Values

Method	Returns / Appends	Important Details
StringAt	The Nth string in the table.	The index is zero-based. The first string is at index 0.
StringAtSb	Appends the Nth string to a supplied StringBuilder.	Use when appending to an existing buffer is preferred.
IntAt	The Nth string converted to an integer.	Returns -1 if no string exists at the index. Returns 0 if the string exists but is not an integer.

Integer lookup note: Because IntAt can return 0 for a non-integer string, check the original string with StringAt if distinguishing 0 from invalid numeric text matters.

Searching the Table

Method	Search Type	Result
FindSubstring	Searches for the first string containing a substring.	Returns the matching string index, starting the search at startIndex. Returns -1 if no match is found.
FindMatch	Matches text against wildcard patterns stored in the table.	Returns the index of the wildcarded string that matches the supplied text, or -1 if no match is found.
WordFollowing	Case-insensitive search for a table entry, then captures the following word.	Returns the matching entry index, or -1 if no match is found. The following word is returned in a StringBuilder.

Wildcard matching: FindMatch expects the strings already stored in the table to contain wildcard patterns, and tests whether the supplied text matches one of those patterns.

Sorting and Clearing

Method	Purpose	Options
Sort	Sorts the strings in the table.	Set ascending to true for ascending order or false for descending order. Set caseSensitive to control case-sensitive sorting.
Clear	Removes all strings from the table.	Use to empty the table before reusing it.

Exporting Strings

Method	Output	Line Ending / Encoding Behavior
GetStrings	Returns selected strings as one string per line.	Pass 0 for both startIdx and count to return the entire table. Set crlf true for CRLF line endings, or false for LF-only line endings.
ToSb	Appends the entire table to a supplied StringBuilder.	Uses CRLF line endings.
SaveToFile	Saves the string table to a file.	The charset controls the output encoding. Set bCrlf true for CRLF line endings or false for LF-only line endings.

Whole-table export: To export the entire table with GetStrings, pass 0 for both startIdx and count.

File Input and Output

Method	Direction	Charset
AppendFromFile	File to string table.	The charset argument specifies the input file encoding, such as utf-8, iso-8859-1, or Shift_JIS.
SaveToFile	String table to file.	The charset argument specifies the output file encoding, such as utf-8, windows-1252, Shift_JIS, or gb2312.

Encoding matters: Specify the correct charset when loading or saving files so non-ASCII text is read and written correctly.

Method Summary by Category

Category	Methods / Properties	Purpose
Add strings	Append, AppendFromFile, AppendFromSb, SplitAndAppend	Add individual strings, lines from files or buffers, or delimited parts from an input string.
Retrieve values	StringAt, StringAtSb, IntAt	Retrieve a string by index, append it to a StringBuilder, or convert it to an integer.
Search	FindSubstring, FindMatch, WordFollowing	Search for substrings, wildcard pattern matches, or words following matched table entries.
Sort and clear	Sort, Clear	Sort the collection or remove all strings.
Export	GetStrings, ToSb, SaveToFile	Emit selected strings, append the full table to a StringBuilder, or save to a file.
Inspect	Count	Get the number of strings in the table.
Diagnostics	LastErrorText	Read diagnostic information after failed or unexpected operations.

Diagnostics and Troubleshooting

Problem Area	Member	What to Check
File import fails	AppendFromFile, LastErrorText	Check the file path, file permissions, charset, and maxLineLen.
Retrieved index is wrong	StringAt, Count	Remember that indexes are zero-based. Valid indexes are 0 through Count - 1.
Integer conversion returns 0	IntAt	The string at the index may exist but not be an integer. Use StringAt to inspect the original text.
Integer conversion returns -1	IntAt	No string exists at the specified index.
Wildcard match is not found	FindMatch	Confirm that the table entries contain the intended wildcard patterns and that the caseSensitive setting is correct.
Substring search misses expected match	FindSubstring	Check startIndex and caseSensitive.
Delimiter splitting behaves unexpectedly	SplitAndAppend	Check whether delimiters inside double quotes or escaped delimiters should be ignored.
Saved file has wrong characters or line endings	SaveToFile	Verify the output charset and whether CRLF or LF line endings should be used.
Need operation details after failure	LastErrorText	Check diagnostic text after failed or unexpected append, search, sort, retrieval, save, or file-load operations.

Common Pitfalls

Pitfall	Better Approach
Forgetting that indexes are zero-based.	The first string is at index 0.
Assuming IntAt returns only parsed integer values.	IntAt returns -1 when the index is missing and 0 when the string exists but is not an integer.
Using SplitAndAppend for multi-character delimiters.	Use it for a single delimiter character.
Expecting delimiters inside quotes to be ignored without enabling the option.	Set exceptDoubleQuoted to true when quoted text may contain delimiters.
Expecting escaped delimiters to be ignored without enabling the option.	Set exceptEscaped to true when backslash-escaped delimiters should not split the input.
Using the wrong charset when reading or writing files.	Supply the correct charset to AppendFromFile or SaveToFile.
Ignoring diagnostics after unexpected behavior.	Check LastErrorText for details.

Best Practices

Recommendation	Reason
Use Count before index-based iteration.	It prevents out-of-range access and makes loops straightforward.
Use AppendFromFile for line-oriented files.	It directly imports one table entry per line using the specified charset.
Use SplitAndAppend for simple delimited input.	It can handle quoted or escaped delimiters when the appropriate options are enabled.
Use FindSubstring when searching table contents.	It returns the index of the first entry containing the target substring.
Use FindMatch when the table stores wildcard patterns.	It matches an input string against the table’s wildcarded entries.
Use SaveToFile with explicit charset and line-ending choices.	This avoids ambiguity when writing text files used by other tools or platforms.
Check LastErrorText after failures.	It provides useful diagnostic detail for failed or unexpected string table operations.

Summary

Chilkat.StringTable is a lightweight ordered collection for storing, loading, searching, sorting, splitting, retrieving, and exporting strings. It is especially useful for line-oriented text, pattern lists, delimited input, and workflows that need simple indexed string access.

The most important practical guidance is to remember that indexes are zero-based, use Count before iteration, specify the correct charset when reading or writing files, use the quote and escape options when splitting delimited text, and inspect LastErrorText whenever an operation fails or produces unexpected results.

Chilkat.StringTable Class Overview