<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="VB6Parse Library Reference - join - Arrays">
<title>join - Arrays - VB6Parse Library Reference</title>
<link rel="stylesheet" href="../../../assets/css/style.css">
<link rel="stylesheet" href="../../../assets/css/docs-style.css">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/github-dark.min.css">
<script src="../../../assets/js/theme-switcher.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/languages/vbnet.min.js"></script>
<script>hljs.highlightAll();</script>
</head>
<body>
<header class="docs-header">
<div class="container">
<h1><a href="../../../index.html">VB6Parse</a> / <a href="../../../library/index.html">Library</a> / <a href="../../../library/functions/arrays/index.html">Arrays</a> / join</h1>
<p class="tagline">VB6 Library Reference</p>
</div>
</header>
<nav class="docs-nav">
<div class="container">
<a href="../../../index.html">Home</a>
<a href="../../../library/index.html">Library Reference</a>
<a href="../../../documentation.html">Documentation</a>
<a href="https://docs.rs/vb6parse" target="_blank">API Docs</a>
<a href="https://github.com/scriptandcompile/vb6parse" target="_blank">GitHub</a>
<button id="theme-toggle" class="theme-toggle" aria-label="Toggle theme">
<span class="theme-icon">🌙</span>
</button>
</div>
</nav>
<main class="container">
<article class="library-item">
<h2 id="join-function">Join Function</h2>
<p>Returns a string created by joining a number of substrings contained in an array.</p>
<h2 id="syntax">Syntax</h2>
<pre><code class="language-text">Join(sourcearray, [delimiter])</code></pre>
<h2 id="parameters">Parameters</h2>
<ul>
<li><strong>sourcearray</strong> (Required): One-dimensional array containing substrings to be joined</li>
<li><strong>delimiter</strong> (Optional): <code>String</code> used to separate the substrings in the returned string</li>
<li>If omitted, space character (" ") is used</li>
<li>If empty string (""), items are concatenated with no separator</li>
</ul>
<h2 id="return-value">Return Value</h2>
<p>Returns a <code>String</code>
- <code>String</code> containing all elements of the array joined by the delimiter
- <code>Empty</code> string ("") if array has zero length
- Returns <code>Null</code> if <code>sourcearray</code> is <code>Null</code>
- Each array element is converted to <code>String</code> before joining
- Non-string elements are automatically converted using <code>Str</code>/<code>CStr</code>
- <code>Empty</code> array elements become empty strings in result
- Trailing / leading spaces in delimiter are preserved</p>
<h2 id="remarks">Remarks</h2>
<p>The <code>Join</code> function is the inverse of the <code>Split</code> function:
- Combines array elements into a single string
- Only works with one-dimensional arrays
- Array elements are converted to strings automatically
- Default delimiter is a space (" ")
- <code>Empty</code> string delimiter concatenates without separators
- <code>Null</code> array returns <code>Null</code> (not an error)
- Empty array (zero length) returns empty string
- Preserves empty array elements as empty strings
- Very efficient for building strings from multiple parts
- Much faster than repeated string concatenation in loops
- Available in VB6 and VBA (added in VB6/Office 2000)
- Common in text processing and file generation
- Works with <code>Variant</code> arrays containing mixed types
- Does not add delimiter after last element</p>
<h3 id="common-errors">Common Errors</h3>
<ul>
<li><strong>Error 13</strong> (Type Mismatch): <code>sourcearray</code> is a multi-dimensional array.</li>
</ul>
<h2 id="performance-considerations">Performance Considerations</h2>
<ul>
<li><strong>Very Efficient</strong>: Join is much faster than repeated concatenation</li>
<li><strong>String Building</strong>: Use Join instead of concatenation in loops</li>
<li><strong>Memory Usage</strong>: Creates single string allocation for result</li>
<li><strong>Large Arrays</strong>: Handles large arrays efficiently</li>
</ul>
<h3 id="performance-comparison">Performance comparison:</h3>
<pre><code class="language-vbnet">' SLOW: Repeated concatenation
Dim result As String
For i = 0 To 999
result = result & arr(i) & ","
Next i
' FAST: Using Join
result = Join(arr, ",")</code></pre>
<h2 id="typical-uses">Typical Uses</h2>
<ol>
<li><strong>CSV Generation</strong>: Create comma-separated value strings</li>
<li><strong>Path Building</strong>: Combine path components with backslashes</li>
<li><strong>SQL Generation</strong>: Build SQL queries from parts</li>
<li><strong>Text Formatting</strong>: Create formatted text from arrays</li>
<li><strong>File Output</strong>: Generate text file content</li>
<li><strong>URL Building</strong>: Construct URLs from components</li>
<li><strong>String Building</strong>: Efficient alternative to concatenation loops</li>
<li><strong>Report Generation</strong>: Format report lines from data arrays</li>
</ol>
<h2 id="limitations">Limitations</h2>
<ul>
<li>Cannot join multi-dimensional arrays (use loops to flatten first)</li>
<li>Returns <code>Null</code> for <code>Null</code> array (not empty <code>String</code>)</li>
<li>No built-in escaping for CSV (must implement manually)</li>
<li>Cannot skip empty elements automatically</li>
<li>No formatting options for numeric values</li>
<li>Delimiter is applied between all elements (no custom logic)</li>
</ul>
<h3 id="platform-and-version-notes">Platform and Version Notes</h3>
<ul>
<li>Added in VB6 and Office 2000 VBA</li>
<li>Not available in VB5 or earlier</li>
<li>Part of <code>VBA.Strings</code> module</li>
<li>Returns <code>String</code> type</li>
<li>Only works with one-dimensional arrays</li>
<li>Automatically converts array elements to <code>String</code></li>
</ul>
<h2 id="related-functions">Related Functions</h2>
<ul>
<li><code>Split</code>: Split string into array (inverse of <code>Join</code>)</li>
<li><code>Filter</code>: Filter array elements based on criteria</li>
<li><code>UBound</code>/<code>LBound</code>: Get array bounds</li>
<li><code>Array</code>: Create array from values</li>
<li><code>Replace</code>: Replace substrings in <code>String</code></li>
</ul>
<h2 id="examples">Examples</h2>
<h3 id="join-with-default-delimiter-space">Join With Default Delimiter (space)</h3>
<pre><code class="language-vbnet">Dim words(2) As String
words(0) = "Hello"
words(1) = "Visual"
words(2) = "Basic"
Debug.Print Join(words) ' "Hello Visual Basic"</code></pre>
<h3 id="join-with-custom-delimiter">Join With Custom Delimiter</h3>
<pre><code class="language-vbnet">' Example 2: Join with custom delimiter
Dim values(3) As String
values(0) = "apple"
values(1) = "banana"
values(2) = "cherry"
values(3) = "date"
Debug.Print Join(values, ", ") ' "apple, banana, cherry, date"
Debug.Print Join(values, " | ") ' "apple | banana | cherry | date"
Debug.Print Join(values, "") ' "applebananacherrydate"</code></pre>
<h3 id="csv-generation">CSV Generation</h3>
<pre><code class="language-vbnet">Dim fields(2) As String
fields(0) = "John Doe"
fields(1) = "Engineer"
fields(2) = "50000"
Dim csvLine As String
csvLine = Join(fields, ",")
Debug.Print csvLine ' "John Doe,Engineer,50000"</code></pre>
<h3 id="working-with-split-and-join">Working with Split and Join</h3>
<pre><code class="language-vbnet">Dim original As String
Dim parts() As String
Dim rebuilt As String
original = "one-two-three-four"
parts = Split(original, "-")
rebuilt = Join(parts, " ")
Debug.Print rebuilt ' "one two three four"</code></pre>
<h2 id="common-patterns">Common Patterns</h2>
<h3 id="pattern-1-build-csv-row">Pattern 1: Build CSV Row</h3>
<pre><code class="language-vbnet">Function BuildCSVRow(fields As Variant) As String
BuildCSVRow = Join(fields, ",")
End Function</code></pre>
<h3 id="pattern-2-join-with-line-breaks">Pattern 2: Join With Line Breaks</h3>
<pre><code class="language-vbnet">Function JoinLines(lines As Variant) As String
JoinLines = Join(lines, vbCrLf)
End Function</code></pre>
<h3 id="pattern-3-build-path-from-components">Pattern 3: Build Path From Components</h3>
<pre><code class="language-vbnet">Function BuildPath(ParamArray parts() As Variant) As String
Dim arr() As String
Dim i As Long
ReDim arr(LBound(parts) To UBound(parts))
For i = LBound(parts) To UBound(parts)
arr(i) = CStr(parts(i))
Next i
BuildPath = Join(arr, "\")
End Function</code></pre>
<h3 id="pattern-4-create-comma-separated-list">Pattern 4: Create Comma-Separated List</h3>
<pre><code class="language-vbnet">Function ToCommaSeparated(items As Variant) As String
If IsArray(items) Then
ToCommaSeparated = Join(items, ", ")
Else
ToCommaSeparated = CStr(items)
End If
End Function</code></pre>
<h3 id="pattern-5-build-sql-in-clause">Pattern 5: Build SQL IN Clause</h3>
<pre><code class="language-vbnet">Function BuildInClause(values As Variant) As String
Dim i As Long
Dim quoted() As String
If Not IsArray(values) Then Exit Function
ReDim quoted(LBound(values) To UBound(values))
For i = LBound(values) To UBound(values)
quoted(i) = "'" & Replace(CStr(values(i)), "'", "''") & "'"
Next i
BuildInClause = Join(quoted, ", ")
End Function</code></pre>
<h3 id="pattern-6-join-non-empty-values-only">Pattern 6: Join Non-Empty Values Only</h3>
<pre><code class="language-vbnet">Function JoinNonEmpty(arr As Variant, delimiter As String) As String
Dim result As Collection
Dim i As Long
Dim temp() As String
Dim count As Long
If Not IsArray(arr) Then Exit Function
Set result = New Collection
For i = LBound(arr) To UBound(arr)
If Len(arr(i)) > 0 Then
result.Add CStr(arr(i))
End If
Next i
If result.Count = 0 Then
JoinNonEmpty = ""
Exit Function
End If
ReDim temp(0 To result.Count - 1)
For i = 1 To result.Count
temp(i - 1) = result(i)
Next i
JoinNonEmpty = Join(temp, delimiter)
End Function</code></pre>
<h3 id="pattern-7-format-array-for-display">Pattern 7: Format Array For Display</h3>
<pre><code class="language-vbnet">Function FormatArray(arr As Variant) As String
If Not IsArray(arr) Then
FormatArray = CStr(arr)
Else
FormatArray = "[" & Join(arr, ", ") & "]"
End If
End Function</code></pre>
<h3 id="pattern-8-build-where-clause">Pattern 8: Build WHERE Clause</h3>
<pre><code class="language-vbnet">Function BuildWhereClause(conditions As Variant) As String
If Not IsArray(conditions) Then Exit Function
If UBound(conditions) < LBound(conditions) Then
BuildWhereClause = ""
Else
BuildWhereClause = Join(conditions, " AND ")
End If
End Function</code></pre>
<h3 id="pattern-9-create-delimited-string-with-quotes">Pattern 9: Create Delimited String With Quotes</h3>
<pre><code class="language-vbnet">Function JoinQuoted(items As Variant, delimiter As String) As String
Dim i As Long
Dim quoted() As String
If Not IsArray(items) Then Exit Function
ReDim quoted(LBound(items) To UBound(items))
For i = LBound(items) To UBound(items)
quoted(i) = Chr(34) & items(i) & Chr(34) ' Chr(34) = "
Next i
JoinQuoted = Join(quoted, delimiter)
End Function</code></pre>
<h3 id="pattern-10-reverse-of-split-for-round-trip">Pattern 10: Reverse of Split for Round-Trip</h3>
<pre><code class="language-vbnet">Function ReverseTransform(text As String) As String
Dim parts() As String
Dim i As Long
parts = Split(text, " ")
' Reverse array
For i = LBound(parts) To (UBound(parts) - LBound(parts)) \ 2 + LBound(parts)
Dim temp As String
temp = parts(i)
parts(i) = parts(UBound(parts) - (i - LBound(parts)))
parts(UBound(parts) - (i - LBound(parts))) = temp
Next i
ReverseTransform = Join(parts, " ")
End Function</code></pre>
<h2 id="advanced-usage-examples">Advanced Usage Examples</h2>
<h3 id="example-1-csv-builder-with-proper-escaping">Example 1: CSV Builder with proper escaping</h3>
<pre><code class="language-vbnet">Public Class CSVBuilder
Private m_rows As Collection
Private Sub Class_Initialize()
Set m_rows = New Collection
End Sub
Public Sub AddRow(ParamArray values() As Variant)
Dim i As Long
Dim fields() As String
ReDim fields(LBound(values) To UBound(values))
For i = LBound(values) To UBound(values)
fields(i) = EscapeCSV(CStr(values(i)))
Next i
m_rows.Add Join(fields, ",")
End Sub
Private Function EscapeCSV(value As String) As String
If InStr(value, ",") > 0 Or InStr(value, Chr(34)) > 0 Or _
InStr(value, vbCrLf) > 0 Then
' Need to quote and escape
EscapeCSV = Chr(34) & Replace(value, Chr(34), Chr(34) & Chr(34)) & Chr(34)
Else
EscapeCSV = value
End If
End Function
Public Function GetCSV() As String
Dim i As Long
Dim lines() As String
If m_rows.Count = 0 Then
GetCSV = ""
Exit Function
End If
ReDim lines(0 To m_rows.Count - 1)
For i = 1 To m_rows.Count
lines(i - 1) = m_rows(i)
Next i
GetCSV = Join(lines, vbCrLf)
End Function
Public Sub Clear()
Set m_rows = New Collection
End Sub
End Class</code></pre>
<h3 id="example-2-string-builder-for-efficient-concatenation">Example 2: String Builder For Efficient Concatenation</h3>
<pre><code class="language-vbnet">Public Class StringBuilder
Private m_parts As Collection
Private m_delimiter As String
Private Sub Class_Initialize()
Set m_parts = New Collection
m_delimiter = ""
End Sub
Public Property Let Delimiter(value As String)
m_delimiter = value
End Property
Public Sub Append(text As String)
m_parts.Add text
End Sub
Public Sub AppendLine(text As String)
m_parts.Add text & vbCrLf
End Sub
Public Function ToString() As String
Dim i As Long
Dim arr() As String
If m_parts.Count = 0 Then
ToString = ""
Exit Function
End If
ReDim arr(0 To m_parts.Count - 1)
For i = 1 To m_parts.Count
arr(i - 1) = m_parts(i)
Next i
ToString = Join(arr, m_delimiter)
End Function
Public Sub Clear()
Set m_parts = New Collection
End Sub
Public Function Length() As Long
Length = Len(ToString())
End Function
End Class</code></pre>
<h3 id="example-3-query-builder-using-join">Example 3: Query Builder Using Join</h3>
<pre><code class="language-vbnet">Public Class QueryBuilder
Private m_select As Collection
Private m_from As String
Private m_where As Collection
Private m_orderBy As Collection
Private Sub Class_Initialize()
Set m_select = New Collection
Set m_where = New Collection
Set m_orderBy = New Collection
End Sub
Public Sub AddField(fieldName As String)
m_select.Add fieldName
End Sub
Public Sub SetTable(tableName As String)
m_from = tableName
End Sub
Public Sub AddCondition(condition As String)
m_where.Add condition
End Sub
Public Sub AddOrderBy(fieldName As String)
m_orderBy.Add fieldName
End Sub
Public Function BuildSQL() As String
Dim sql As String
Dim fields() As String
Dim conditions() As String
Dim orderFields() As String
Dim i As Long
' SELECT clause
If m_select.Count = 0 Then
sql = "SELECT *"
Else
ReDim fields(0 To m_select.Count - 1)
For i = 1 To m_select.Count
fields(i - 1) = m_select(i)
Next i
sql = "SELECT " & Join(fields, ", ")
End If
' FROM clause
If m_from <> "" Then
sql = sql & " FROM " & m_from
End If
' WHERE clause
If m_where.Count > 0 Then
ReDim conditions(0 To m_where.Count - 1)
For i = 1 To m_where.Count
conditions(i - 1) = m_where(i)
Next i
sql = sql & " WHERE " & Join(conditions, " AND ")
End If
' ORDER BY clause
If m_orderBy.Count > 0 Then
ReDim orderFields(0 To m_orderBy.Count - 1)
For i = 1 To m_orderBy.Count
orderFields(i - 1) = m_orderBy(i)
Next i
sql = sql & " ORDER BY " & Join(orderFields, ", ")
End If
BuildSQL = sql
End Function
Public Sub Clear()
Set m_select = New Collection
m_from = ""
Set m_where = New Collection
Set m_orderBy = New Collection
End Sub
End Class</code></pre>
<h3 id="example-4-report-formatter">Example 4: Report Formatter</h3>
<pre><code class="language-vbnet">Public Class ReportFormatter
Public Function FormatTable(data As Variant, headers As Variant, _
Optional delimiter As String = " | ") As String
Dim lines As Collection
Dim i As Long, j As Long
Dim row() As String
Dim allLines() As String
Set lines = New Collection
' Add header
If IsArray(headers) Then
lines.Add Join(headers, delimiter)
' Add separator
ReDim row(LBound(headers) To UBound(headers))
For j = LBound(headers) To UBound(headers)
row(j) = String(Len(headers(j)), "-")
Next j
lines.Add Join(row, delimiter)
End If
' Add data rows
If IsArray(data) Then
For i = LBound(data) To UBound(data)
If IsArray(data(i)) Then
lines.Add Join(data(i), delimiter)
Else
lines.Add CStr(data(i))
End If
Next i
End If
' Convert collection to array and join
ReDim allLines(0 To lines.Count - 1)
For i = 1 To lines.Count
allLines(i - 1) = lines(i)
Next i
FormatTable = Join(allLines, vbCrLf)
End Function
Public Function FormatList(items As Variant, _
Optional prefix As String = "- ") As String
Dim i As Long
Dim lines() As String
If Not IsArray(items) Then
FormatList = prefix & CStr(items)
Exit Function
End If
ReDim lines(LBound(items) To UBound(items))
For i = LBound(items) To UBound(items)
lines(i) = prefix & CStr(items(i))
Next i
FormatList = Join(lines, vbCrLf)
End Function
End Class</code></pre>
<h2 id="error-handling">Error Handling</h2>
<p>Join handles several special cases:</p>
<h3 id="empty-array-returns-empty-string">Empty Array Returns Empty String</h3>
<pre><code class="language-vbnet">Dim emptyArr() As String
ReDim emptyArr(0 To -1) ' Zero-length array
Debug.Print Join(emptyArr, ",") ' Returns ""</code></pre>
<h3 id="null-array-returns-null">Null Array Returns Null</h3>
<pre><code class="language-vbnet">Dim nullArr As Variant
nullArr = Null
Debug.Print IsNull(Join(nullArr, ",")) ' True</code></pre>
<h3 id="works-with-mixed-type-variant-arrays">Works With Mixed-Type Variant Arrays</h3>
<pre><code class="language-vbnet">Dim mixed(2) As Variant
mixed(0) = 123
mixed(1) = "text"
mixed(2) = True
Debug.Print Join(mixed, "-") ' "123-text-True"</code></pre>
<h3 id="multi-dimensional-arrays-cause-type-mismatch-error">Multi-Dimensional Arrays Cause Type Mismatch Error</h3>
<pre><code class="language-vbnet">Dim multi(1, 1) As String
' Join(multi, ",") ' Error 13: Type Mismatch</code></pre>
<h2 id="best-practices">Best Practices</h2>
<ol>
<li><strong>Use Join for String Building</strong>: Much faster than repeated concatenation</li>
<li><strong>CSV Generation</strong>: Properly escape values containing delimiters</li>
<li><strong>Empty Delimiter</strong>: Use "" to concatenate without separators</li>
<li><strong>Check Array</strong>: Verify array exists before calling <code>Join</code></li>
<li><strong>Null Handling</strong>: Be aware <code>Join</code> returns <code>Null</code> for <code>Null</code> arrays</li>
<li><strong>Line Breaks</strong>: Use <code>vbCrLf</code>, <code>vbLf</code>, or <code>vbCr</code> as delimiter for multi-line text</li>
<li><strong>Collection to String</strong>: Convert <code>Collection</code> to array first, then <code>Join</code></li>
<li><strong>Type Conversion</strong>: <code>Join</code> automatically converts non-string elements</li>
</ol>
<h2 id="comparison-with-related-functions">Comparison with Related Functions</h2>
<table>
<thead>
<tr>
<th>Function</th>
<th>Purpose</th>
<th>Input</th>
<th>Output</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>Join</code></td>
<td>Combine array to string</td>
<td><code>Array</code></td>
<td><code>String</code></td>
</tr>
<tr>
<td><code>Split</code></td>
<td>Split string to array</td>
<td><code>String</code></td>
<td><code>Array</code></td>
</tr>
<tr>
<td><code>String</code> concatenation (&)</td>
<td>Combine two strings</td>
<td><code>Strings</code></td>
<td><code>String</code></td>
</tr>
<tr>
<td><code>Filter</code></td>
<td>Filter array elements</td>
<td><code>Array</code></td>
<td><code>Array</code></td>
</tr>
<tr>
<td><code>UBound</code>/<code>LBound</code></td>
<td>Get array bounds</td>
<td><code>Array</code></td>
<td><code>Long</code></td>
</tr>
</tbody>
</table>
<h2 id="join-vs-string-concatenation">Join vs String Concatenation</h2>
<pre><code class="language-vbnet">Dim arr(2) As String
arr(0) = "A"
arr(1) = "B"
arr(2) = "C"
' Using Join (FAST)
result = Join(arr, ",") ' "A,B,C"
' Using concatenation (SLOW)
result = arr(0) & "," & arr(1) & "," & arr(2) ' "A,B,C"
' For large arrays, Join is dramatically faster</code></pre>
<h2 id="join-and-split-round-trip">Join and Split Round-Trip</h2>
<pre><code class="language-vbnet">' Original string
original = "apple,banana,cherry"
' Split into array
parts = Split(original, ",") ' ["apple", "banana", "cherry"]
' Join back to string
rebuilt = Join(parts, ",") ' "apple,banana,cherry"
Debug.Print original = rebuilt ' True - perfect round-trip</code></pre>
</article>
<div style="margin-top: 3rem; padding-top: 2rem; border-top: 1px solid var(--border-color);">
<p>
<a href="index.html">← Back to Arrays</a> |
<a href="../index.html">View all functions</a>
</p>
</div>
</main>
<footer>
<div class="container">
<p>© 2024-2026 VB6Parse Contributors. Licensed under the MIT License.</p>
</div>
</footer>
</body>
</html>