<!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 - string_function - String">
<title>string_function - String - 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/string/index.html">String</a> / string_function</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">
<p>VB6 String Function
The <code>String</code> function returns a string consisting of a repeating character.</p>
<h2 id="syntax">Syntax</h2>
<pre><code class="language-vbnet">String(number, character)</code></pre>
<h2 id="parameters">Parameters</h2>
<ul>
<li><code>number</code>: Required. Long integer specifying the length of the returned string. Must be between 0 and approximately 2 billion (limited by available memory).</li>
<li><code>character</code>: Required. Variant specifying the character code or string expression whose first character is used.</li>
<li>If <code>character</code> is a numeric value, it's treated as a character code (0-255)</li>
<li>If <code>character</code> is a string, only the first character is used</li>
</ul>
<h2 id="returns">Returns</h2>
<p>Returns a <code>Variant</code> (String) containing a string of length <code>number</code> composed of the repeating character.</p>
<h2 id="remarks">Remarks</h2>
<p>The <code>String</code> function creates strings filled with repeating characters:
- <strong>Character code</strong>: If <code>character</code> is numeric (0-255), it's interpreted as an ASCII/ANSI character code
- <strong>String argument</strong>: If <code>character</code> is a string, only the first character is used (rest is ignored)
- <strong>Empty string</strong>: If <code>number</code> is 0, returns an empty string ("")
- <strong>Negative number</strong>: Causes Error 5 (Invalid procedure call or argument)
- <strong>Performance</strong>: Very efficient for creating repeating character strings
- <strong>Common uses</strong>: Creating separators, padding, borders, rulers, progress bars
- <strong>Memory limit</strong>: <code>number</code> is limited by available memory (typically up to ~2 billion characters)
- <strong>Related function</strong>: <code>Space</code> function is equivalent to <code>String(n, 32)</code> or <code>String(n, " ")</code></p>
<h3 id="character-code-examples">Character Code Examples</h3>
<ul>
<li><code>String(5, 65)</code> returns "AAAAA" (65 is ASCII code for 'A')</li>
<li><code>String(3, 42)</code> returns "**<em>" (42 is ASCII code for '</em>')</li>
<li><code>String(10, 45)</code> returns "----------" (45 is ASCII code for '-')</li>
<li><code>String(4, 61)</code> returns "====" (61 is ASCII code for '=')</li>
</ul>
<h3 id="string-argument-examples">String Argument Examples</h3>
<ul>
<li><code>String(5, "A")</code> returns "AAAAA"</li>
<li><code>String(3, "*")</code> returns "***"</li>
<li><code>String(10, "-")</code> returns "----------"</li>
<li><code>String(3, "Hello")</code> returns "HHH" (only first character used)</li>
</ul>
<h2 id="typical-uses">Typical Uses</h2>
<ol>
<li><strong>Line Separators</strong>: Create horizontal lines for text output or reports</li>
<li><strong>Padding</strong>: Pad strings to specific widths for alignment</li>
<li><strong>Borders</strong>: Create box borders for text displays</li>
<li><strong>Progress Indicators</strong>: Build progress bars or loading indicators</li>
<li><strong>Masking</strong>: Create mask strings (asterisks for passwords)</li>
<li><strong>Rulers</strong>: Create ruler lines for text editors or debuggers</li>
<li><strong>Fill Characters</strong>: Initialize strings with specific fill characters</li>
<li><strong>Visual Markers</strong>: Create visual separators in console or debug output</li>
</ol>
<h2 id="basic-examples">Basic Examples</h2>
<h3 id="example-1-creating-line-separators">Example 1: Creating Line Separators</h3>
<pre><code class="language-vbnet">Dim separator As String
separator = String(50, "-") ' "--------------------------------------------------"
separator = String(40, "=") ' "========================================"
separator = String(30, "*") ' "******************************"
separator = String(20, 45) ' "--------------------" (45 = '-')</code></pre>
<h3 id="example-2-padding-strings">Example 2: Padding Strings</h3>
<pre><code class="language-vbnet">Dim text As String
Dim padded As String
text = "Title"
' Left padding with spaces
padded = String(10 - Len(text), " ") & text ' " Title"
' Right padding with dots
padded = text & String(20 - Len(text), ".") ' "Title..............."</code></pre>
<h3 id="example-3-creating-box-borders">Example 3: Creating Box Borders</h3>
<pre><code class="language-vbnet">Sub DrawBox(width As Integer)
Dim topBottom As String
Dim side As String
topBottom = "+" & String(width - 2, "-") & "+"
side = "|" & String(width - 2, " ") & "|"
Debug.Print topBottom
Debug.Print side
Debug.Print side
Debug.Print topBottom
End Sub</code></pre>
<h3 id="example-4-progress-bar">Example 4: Progress Bar</h3>
<pre><code class="language-vbnet">Function CreateProgressBar(percent As Integer, width As Integer) As String
Dim filled As Integer
Dim empty As Integer
filled = (percent * width) \ 100
empty = width - filled
CreateProgressBar = "[" & String(filled, "#") & String(empty, " ") & "]"
' Example: [##### ] for 50%
End Function</code></pre>
<h2 id="common-patterns">Common Patterns</h2>
<h3 id="pattern-1-create-horizontal-line">Pattern 1: Create Horizontal Line</h3>
<pre><code class="language-vbnet">Function HorizontalLine(width As Integer, Optional char As String = "-") As String
HorizontalLine = String(width, char)
End Function</code></pre>
<h3 id="pattern-2-center-text">Pattern 2: Center Text</h3>
<pre><code class="language-vbnet">Function CenterText(text As String, width As Integer) As String
Dim padding As Integer
Dim leftPad As Integer
Dim rightPad As Integer
If Len(text) >= width Then
CenterText = Left$(text, width)
Exit Function
End If
padding = width - Len(text)
leftPad = padding \ 2
rightPad = padding - leftPad
CenterText = String(leftPad, " ") & text & String(rightPad, " ")
End Function</code></pre>
<h3 id="pattern-3-pad-number-with-zeros">Pattern 3: Pad Number with Zeros</h3>
<pre><code class="language-vbnet">Function PadWithZeros(value As Long, totalWidth As Integer) As String
Dim numStr As String
numStr = CStr(value)
If Len(numStr) >= totalWidth Then
PadWithZeros = numStr
Else
PadWithZeros = String(totalWidth - Len(numStr), "0") & numStr
End If
End Function</code></pre>
<h3 id="pattern-4-create-table-row-separator">Pattern 4: Create Table Row Separator</h3>
<pre><code class="language-vbnet">Function TableSeparator(columnWidths() As Integer) As String
Dim i As Integer
Dim result As String
result = "+"
For i = LBound(columnWidths) To UBound(columnWidths)
result = result & String(columnWidths(i), "-") & "+"
Next i
TableSeparator = result
End Function</code></pre>
<h3 id="pattern-5-mask-sensitive-data">Pattern 5: Mask Sensitive Data</h3>
<pre><code class="language-vbnet">Function MaskString(text As String, Optional maskChar As String = "*") As String
MaskString = String(Len(text), maskChar)
End Function</code></pre>
<h3 id="pattern-6-indent-text">Pattern 6: Indent Text</h3>
<pre><code class="language-vbnet">Function IndentText(text As String, level As Integer, _
Optional indentSize As Integer = 4) As String
IndentText = String(level * indentSize, " ") & text
End Function</code></pre>
<h3 id="pattern-7-create-ruler">Pattern 7: Create Ruler</h3>
<pre><code class="language-vbnet">Function CreateRuler(length As Integer) As String
Dim i As Integer
Dim ruler As String
Dim markers As String
' Create tick marks every 10 characters
ruler = ""
markers = ""
For i = 1 To length
If i Mod 10 = 0 Then
ruler = ruler & "|"
markers = markers & CStr(i \ 10 Mod 10)
Else
ruler = ruler & "."
markers = markers & " "
End If
Next i
CreateRuler = markers & vbCrLf & ruler
End Function</code></pre>
<h3 id="pattern-8-fill-to-width">Pattern 8: Fill to Width</h3>
<pre><code class="language-vbnet">Function FillToWidth(text As String, width As Integer, _
Optional fillChar As String = " ") As String
If Len(text) >= width Then
FillToWidth = Left$(text, width)
Else
FillToWidth = text & String(width - Len(text), fillChar)
End If
End Function</code></pre>
<h3 id="pattern-9-create-loading-animation">Pattern 9: Create Loading Animation</h3>
<pre><code class="language-vbnet">Function LoadingBar(step As Integer, totalSteps As Integer, width As Integer) As String
Dim filled As Integer
filled = (step * width) \ totalSteps
LoadingBar = String(filled, "=") & ">" & String(width - filled - 1, " ")
End Function</code></pre>
<h3 id="pattern-10-duplicate-character">Pattern 10: Duplicate Character</h3>
<pre><code class="language-vbnet">Function RepeatChar(char As String, count As Integer) As String
' Alias for String function with clearer name
RepeatChar = String(count, char)
End Function</code></pre>
<h2 id="advanced-usage">Advanced Usage</h2>
<h3 id="example-1-text-box-drawer">Example 1: Text Box Drawer</h3>
<pre><code class="language-vbnet">' Class: TextBoxDrawer
' Draws ASCII boxes around text
Option Explicit
Private m_Width As Integer
Private m_Padding As Integer
Public Sub Initialize(width As Integer, Optional padding As Integer = 1)
m_Width = width
m_Padding = padding
End Sub
Public Function DrawBox(title As String, lines() As String) As String
Dim result As String
Dim i As Integer
Dim maxLen As Integer
' Find maximum line length
maxLen = Len(title)
For i = LBound(lines) To UBound(lines)
If Len(lines(i)) > maxLen Then maxLen = Len(lines(i))
Next i
' Adjust width if needed
If m_Width < maxLen + (m_Padding * 2) + 2 Then
m_Width = maxLen + (m_Padding * 2) + 2
End If
' Top border
result = "+" & String(m_Width - 2, "-") & "+" & vbCrLf
' Title (centered)
If Len(title) > 0 Then
result = result & "|" & CenterInWidth(title, m_Width - 2) & "|" & vbCrLf
result = result & "+" & String(m_Width - 2, "-") & "+" & vbCrLf
End If
' Content lines
For i = LBound(lines) To UBound(lines)
result = result & "|" & PadLine(lines(i), m_Width - 2) & "|" & vbCrLf
Next i
' Bottom border
result = result & "+" & String(m_Width - 2, "-") & "+"
DrawBox = result
End Function
Private Function CenterInWidth(text As String, width As Integer) As String
Dim leftPad As Integer
Dim rightPad As Integer
Dim totalPad As Integer
totalPad = width - Len(text)
leftPad = totalPad \ 2
rightPad = totalPad - leftPad
CenterInWidth = String(leftPad, " ") & text & String(rightPad, " ")
End Function
Private Function PadLine(text As String, width As Integer) As String
Dim content As String
content = String(m_Padding, " ") & text
PadLine = content & String(width - Len(content), " ")
End Function</code></pre>
<h3 id="example-2-progress-bar-generator">Example 2: Progress Bar Generator</h3>
<pre><code class="language-vbnet">' Class: ProgressBarGenerator
' Creates customizable progress bars
Option Explicit
Private m_Width As Integer
Private m_FilledChar As String
Private m_EmptyChar As String
Private m_ShowPercent As Boolean
Public Sub Initialize(width As Integer, Optional filledChar As String = "#", _
Optional emptyChar As String = "-", _
Optional showPercent As Boolean = True)
m_Width = width
m_FilledChar = filledChar
m_EmptyChar = emptyChar
m_ShowPercent = showPercent
End Sub
Public Function Generate(current As Long, total As Long) As String
Dim percent As Integer
Dim filled As Integer
Dim empty As Integer
Dim bar As String
If total = 0 Then
Generate = "[" & String(m_Width, m_EmptyChar) & "]"
Exit Function
End If
percent = CInt((current * 100) / total)
If percent > 100 Then percent = 100
filled = (percent * m_Width) \ 100
empty = m_Width - filled
bar = "[" & String(filled, m_FilledChar) & String(empty, m_EmptyChar) & "]"
If m_ShowPercent Then
bar = bar & " " & Format$(percent, "000") & "%"
End If
Generate = bar
End Function
Public Function GenerateIndeterminate(step As Integer) As String
' Animated indeterminate progress bar
Dim pos As Integer
Dim blockSize As Integer
blockSize = 5
pos = step Mod (m_Width + blockSize)
If pos < blockSize Then
GenerateIndeterminate = "[" & String(pos, m_FilledChar) & _
String(m_Width - pos, m_EmptyChar) & "]"
ElseIf pos < m_Width Then
GenerateIndeterminate = "[" & String(pos - blockSize, m_EmptyChar) & _
String(blockSize, m_FilledChar) & _
String(m_Width - pos, m_EmptyChar) & "]"
Else
GenerateIndeterminate = "[" & String(m_Width - (pos - m_Width), m_EmptyChar) & _
String(pos - m_Width, m_FilledChar) & "]"
End If
End Function</code></pre>
<h3 id="example-3-table-formatter-module">Example 3: Table Formatter Module</h3>
<pre><code class="language-vbnet">' Module: TableFormatter
' Creates formatted ASCII tables
Option Explicit
Public Function CreateTable(headers() As String, data() As String, _
columnWidths() As Integer) As String
Dim result As String
Dim i As Integer
Dim j As Integer
Dim row As Integer
Dim col As Integer
' Top border
result = CreateBorder(columnWidths, True) & vbCrLf
' Headers
result = result & CreateRow(headers, columnWidths) & vbCrLf
' Separator
result = result & CreateBorder(columnWidths, False) & vbCrLf
' Data rows
row = LBound(data, 1)
Do While row <= UBound(data, 1)
Dim rowData() As String
ReDim rowData(LBound(headers) To UBound(headers))
For col = LBound(headers) To UBound(headers)
rowData(col) = data(row, col)
Next col
result = result & CreateRow(rowData, columnWidths) & vbCrLf
row = row + 1
Loop
' Bottom border
result = result & CreateBorder(columnWidths, True)
CreateTable = result
End Function
Private Function CreateBorder(columnWidths() As Integer, heavy As Boolean) As String
Dim i As Integer
Dim result As String
Dim corner As String
Dim line As String
If heavy Then
corner = "+"
line = "="
Else
corner = "+"
line = "-"
End If
result = corner
For i = LBound(columnWidths) To UBound(columnWidths)
result = result & String(columnWidths(i) + 2, line) & corner
Next i
CreateBorder = result
End Function
Private Function CreateRow(cells() As String, columnWidths() As Integer) As String
Dim i As Integer
Dim result As String
Dim cell As String
result = "|"
For i = LBound(cells) To UBound(cells)
cell = " " & cells(i)
If Len(cell) < columnWidths(i) + 1 Then
cell = cell & String(columnWidths(i) + 1 - Len(cell), " ")
End If
result = result & cell & " |"
Next i
CreateRow = result
End Function</code></pre>
<h3 id="example-4-text-padding-utilities">Example 4: Text Padding Utilities</h3>
<pre><code class="language-vbnet">' Module: TextPaddingUtils
' Utilities for padding and aligning text
Option Explicit
Public Function PadLeft(text As String, width As Integer, _
Optional padChar As String = " ") As String
If Len(text) >= width Then
PadLeft = text
Else
PadLeft = String(width - Len(text), padChar) & text
End If
End Function
Public Function PadRight(text As String, width As Integer, _
Optional padChar As String = " ") As String
If Len(text) >= width Then
PadRight = text
Else
PadRight = text & String(width - Len(text), padChar)
End If
End Function
Public Function PadCenter(text As String, width As Integer, _
Optional padChar As String = " ") As String
Dim totalPad As Integer
Dim leftPad As Integer
Dim rightPad As Integer
If Len(text) >= width Then
PadCenter = text
Exit Function
End If
totalPad = width - Len(text)
leftPad = totalPad \ 2
rightPad = totalPad - leftPad
PadCenter = String(leftPad, padChar) & text & String(rightPad, padChar)
End Function
Public Function CreateLine(width As Integer, Optional lineChar As String = "-") As String
CreateLine = String(width, lineChar)
End Function
Public Function FrameText(text As String, width As Integer, _
Optional frameChar As String = "*") As String
Dim topBottom As String
Dim middle As String
topBottom = String(width, frameChar)
middle = frameChar & PadCenter(text, width - 2) & frameChar
FrameText = topBottom & vbCrLf & middle & vbCrLf & topBottom
End Function
Public Function Underline(text As String, Optional underlineChar As String = "-") As String
Underline = text & vbCrLf & String(Len(text), underlineChar)
End Function
Public Function NumberedLine(lineNum As Integer, text As String, _
totalWidth As Integer) As String
Dim numStr As String
numStr = PadLeft(CStr(lineNum), 4) & ": "
NumberedLine = numStr & text & String(totalWidth - Len(numStr) - Len(text), " ")
End Function</code></pre>
<h2 id="error-handling">Error Handling</h2>
<p>The <code>String</code> function can raise the following errors:
- <strong>Error 5 (Invalid procedure call or argument)</strong>: If <code>number</code> is negative
- <strong>Error 6 (Overflow)</strong>: If <code>number</code> is too large (exceeds memory limits)
- <strong>Error 13 (Type mismatch)</strong>: If <code>character</code> cannot be converted to a valid character
- <strong>Error 5 (Invalid procedure call)</strong>: If <code>character</code> is a numeric value outside 0-255 range</p>
<h2 id="performance-notes">Performance Notes</h2>
<ul>
<li>Very fast and efficient for creating repeating character strings</li>
<li>More efficient than concatenating characters in a loop</li>
<li>Memory allocation is done once for the entire string</li>
<li>For very large strings (millions of characters), consider memory constraints</li>
<li>Slightly faster than equivalent loop-based approaches</li>
</ul>
<h2 id="best-practices">Best Practices</h2>
<ol>
<li><strong>Use descriptive variable names</strong> when storing String results (e.g., <code>separator</code>, <code>padding</code>)</li>
<li><strong>Validate number parameter</strong> to ensure it's non-negative before calling</li>
<li><strong>Use named constants</strong> for common character codes (e.g., <code>Const ASTERISK = 42</code>)</li>
<li><strong>Prefer string literals</strong> over character codes for clarity (e.g., <code>String(5, "*")</code> vs <code>String(5, 42)</code>)</li>
<li><strong>Consider Space function</strong> for creating space-filled strings (<code>Space(n)</code> vs <code>String(n, " ")</code>)</li>
<li><strong>Cache repeated strings</strong> if used multiple times in a function</li>
<li><strong>Check string length</strong> before padding operations to avoid overflow</li>
<li><strong>Use for visual elements</strong> like separators, borders, and progress indicators</li>
<li><strong>Document character choice</strong> when using character codes instead of string literals</li>
<li><strong>Test with edge cases</strong> like <code>number = 0</code> and very large values</li>
</ol>
<h2 id="comparison-table">Comparison Table</h2>
<table>
<thead>
<tr>
<th>Function</th>
<th>Purpose</th>
<th>Example</th>
<th>Result</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>String</code></td>
<td>Repeat character</td>
<td><code>String(5, "*")</code></td>
<td><code>"*****"</code></td>
</tr>
<tr>
<td><code>Space</code></td>
<td>Repeat space</td>
<td><code>Space(5)</code></td>
<td><code>" "</code></td>
</tr>
<tr>
<td><code>String$</code></td>
<td>Type-declared variant</td>
<td><code>String$(5, 42)</code></td>
<td><code>"*****"</code></td>
</tr>
</tbody>
</table>
<h2 id="platform-notes">Platform Notes</h2>
<ul>
<li>Available in VB6 and VBA</li>
<li>Not available in <code>VBScript</code> (use custom function instead)</li>
<li><code>String$</code> variant returns String type directly (slightly faster)</li>
<li>Behavior consistent across all platforms</li>
<li>Character codes follow ANSI/ASCII standard (0-255)</li>
<li>Maximum string length limited by available memory</li>
</ul>
<h2 id="limitations">Limitations</h2>
<ul>
<li>Cannot create strings with multiple different repeating characters in one call</li>
<li>Character code must be 0-255 (no Unicode character codes)</li>
<li>If <code>character</code> is a string, only first character is used (no validation of length)</li>
<li>Very large <code>number</code> values can cause out-of-memory errors</li>
<li>No built-in way to create alternating patterns</li>
<li>Cannot specify different characters at different positions</li>
</ul>
</article>
<div style="margin-top: 3rem; padding-top: 2rem; border-top: 1px solid var(--border-color);">
<p>
<a href="index.html">← Back to String</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>