<!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 - str_dollar - String">
<title>str_dollar - 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> / str_dollar</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">
<h1 id="str-function">Str$ Function</h1>
<p>The <code>Str$</code> function in Visual Basic 6 converts a numeric value to a string representation.
The dollar sign (<code>$</code>) suffix indicates that this function always returns a <code>String</code> type,
never a <code>Variant</code>.</p>
<h2 id="syntax">Syntax</h2>
<pre><code class="language-vbnet">Str$(number)</code></pre>
<h2 id="parameters">Parameters</h2>
<ul>
<li><code>number</code> - Required. Any valid numeric expression. Can be of type <code>Byte</code>, <code>Integer</code>, <code>Long</code>,
<code>Single</code>, <code>Double</code>, or <code>Currency</code>.</li>
</ul>
<h2 id="return-value">Return Value</h2>
<p>Returns a <code>String</code> representation of the number. Positive numbers include a leading space
for the sign position. Negative numbers include a leading minus sign (-).</p>
<h2 id="behavior-and-characteristics">Behavior and Characteristics</h2>
<h3 id="sign-handling">Sign Handling</h3>
<ul>
<li>Positive numbers: Include a leading space (e.g., " 123")</li>
<li>Negative numbers: Include a leading minus sign (e.g., "-123")</li>
<li>Zero: Returns " 0" (with leading space)</li>
<li>The leading space reserves position for the sign</li>
</ul>
<h3 id="numeric-formatting">Numeric Formatting</h3>
<ul>
<li>No thousands separators (e.g., "1000" not "1,000")</li>
<li>Scientific notation for very large or very small numbers</li>
<li>Floating-point numbers may show precision artifacts</li>
<li>No control over decimal places</li>
</ul>
<h3 id="type-differences-str-vs-str">Type Differences: <code>Str$</code> vs <code>Str</code></h3>
<ul>
<li><code>Str$</code>: Always returns <code>String</code> type (never <code>Variant</code>)</li>
<li><code>Str</code>: Returns <code>Variant</code> containing a string</li>
<li>Use <code>Str$</code> when you need guaranteed <code>String</code> return type</li>
<li>Use <code>Str</code> when working with <code>Variant</code> variables</li>
</ul>
<h2 id="common-usage-patterns">Common Usage Patterns</h2>
<h3 id="1-basic-number-to-string-conversion">1. Basic Number to String Conversion</h3>
<pre><code class="language-vbnet">Dim numStr As String
numStr = Str$(123) ' Returns " 123" (note leading space)
numStr = Str$(-45) ' Returns "-45"</code></pre>
<h3 id="2-concatenating-numbers-with-text">2. Concatenating Numbers with Text</h3>
<pre><code class="language-vbnet">Function FormatMessage(count As Integer) As String
FormatMessage = "Found" & Str$(count) & " items"
End Function
Debug.Print FormatMessage(5) ' "Found 5 items"</code></pre>
<h3 id="3-trimming-the-leading-space">3. Trimming the Leading Space</h3>
<pre><code class="language-vbnet">Function NumberToString(value As Long) As String
NumberToString = LTrim$(Str$(value))
End Function
Dim result As String
result = NumberToString(100) ' Returns "100" (no leading space)</code></pre>
<h3 id="4-building-comma-separated-values">4. Building Comma-Separated Values</h3>
<pre><code class="language-vbnet">Function BuildCSV(values() As Integer) As String
Dim i As Integer
Dim result As String
For i = LBound(values) To UBound(values)
If i > LBound(values) Then result = result & ","
result = result & LTrim$(Str$(values(i)))
Next i
BuildCSV = result
End Function</code></pre>
<h3 id="5-logging-and-debug-output">5. Logging and Debug Output</h3>
<pre><code class="language-vbnet">Sub LogValue(name As String, value As Double)
Debug.Print name & " =" & Str$(value)
End Sub</code></pre>
<h3 id="6-creating-numeric-labels">6. Creating Numeric Labels</h3>
<pre><code class="language-vbnet">Function CreateLabel(index As Integer) As String
CreateLabel = "Item" & LTrim$(Str$(index))
End Function
Dim label As String
label = CreateLabel(42) ' Returns "Item42"</code></pre>
<h3 id="7-file-output-formatting">7. File Output Formatting</h3>
<pre><code class="language-vbnet">Sub WriteDataLine(fileNum As Integer, id As Long, amount As Currency)
Print #fileNum, LTrim$(Str$(id)) & "," & LTrim$(Str$(amount))
End Sub</code></pre>
<h3 id="8-array-index-display">8. Array Index Display</h3>
<pre><code class="language-vbnet">Sub ShowArrayContents(arr() As Integer)
Dim i As Integer
For i = LBound(arr) To UBound(arr)
Debug.Print "[" & LTrim$(Str$(i)) & "] = " & LTrim$(Str$(arr(i)))
Next i
End Sub</code></pre>
<h3 id="9-simple-calculator-display">9. Simple Calculator Display</h3>
<pre><code class="language-vbnet">Function UpdateDisplay(value As Double) As String
UpdateDisplay = LTrim$(Str$(value))
End Function</code></pre>
<h3 id="10-building-sql-statements">10. Building SQL Statements</h3>
<pre><code class="language-vbnet">Function BuildQuery(userId As Long) As String
BuildQuery = "SELECT * FROM Users WHERE ID = " & LTrim$(Str$(userId))
End Function</code></pre>
<h2 id="related-functions">Related Functions</h2>
<ul>
<li><code>Str()</code> - Returns a <code>Variant</code> containing the string representation of a number</li>
<li><code>CStr()</code> - Converts an expression to a <code>String</code> (no leading space for positive numbers)</li>
<li><code>Format$()</code> - Provides extensive formatting control for numeric values</li>
<li><code>Val()</code> - Converts a string to a numeric value (inverse operation)</li>
<li><code>LTrim$()</code> - Removes leading spaces (often used with <code>Str$</code>)</li>
<li><code>Hex$()</code> - Converts a number to hexadecimal string</li>
<li><code>Oct$()</code> - Converts a number to octal string</li>
</ul>
<h2 id="best-practices">Best Practices</h2>
<h3 id="when-to-use-str-vs-cstr-vs-format">When to Use <code>Str$</code> vs <code>CStr</code> vs <code>Format$</code></h3>
<pre><code class="language-vbnet">Dim value As Integer
value = 42
' Str$ includes leading space for positive numbers
Debug.Print Str$(value) ' " 42"
' CStr has no leading space
Debug.Print CStr(value) ' "42"
' Format$ provides control over formatting
Debug.Print Format$(value, "000") ' "042"</code></pre>
<h3 id="always-trim-for-display">Always Trim for Display</h3>
<pre><code class="language-vbnet">' Without trim (has leading space for positive numbers)
Label1.Caption = Str$(count) ' " 5"
' With trim (clean output)
Label1.Caption = LTrim$(Str$(count)) ' "5"
' Or use CStr instead
Label1.Caption = CStr(count) ' "5"</code></pre>
<h3 id="use-format-for-formatted-output">Use <code>Format$</code> for Formatted Output</h3>
<pre><code class="language-vbnet">' Str$ has no formatting control
Debug.Print Str$(1234.5678) ' " 1234.5678"
' Format$ provides control
Debug.Print Format$(1234.5678, "#,##0.00") ' "1,234.57"</code></pre>
<h3 id="handle-negative-numbers">Handle Negative Numbers</h3>
<pre><code class="language-vbnet">Function SafeConvert(value As Long) As String
' Str$ handles negative numbers correctly
SafeConvert = LTrim$(Str$(value))
' For negative: "-123", for positive: "123"
End Function</code></pre>
<h2 id="performance-considerations">Performance Considerations</h2>
<ul>
<li><code>Str$</code> is very fast for simple conversions</li>
<li>Faster than <code>Format$</code> when formatting is not needed</li>
<li>Similar performance to <code>CStr</code></li>
<li>No significant overhead for any numeric type</li>
</ul>
<pre><code class="language-vbnet">' Fast: simple conversion
For i = 1 To 10000
text = LTrim$(Str$(i))
Next i
' Slower: formatted conversion (but more control)
For i = 1 To 10000
text = Format$(i, "0000")
Next i</code></pre>
<h2 id="common-pitfalls">Common Pitfalls</h2>
<h3 id="1-leading-space-for-positive-numbers">1. Leading Space for Positive Numbers</h3>
<pre><code class="language-vbnet">Dim result As String
result = Str$(100) ' " 100" (note the leading space!)
' This can cause problems in comparisons
If Str$(100) = "100" Then ' FALSE! (" 100" <> "100")
Debug.Print "Match"
End If
' Use LTrim$ or CStr instead
If LTrim$(Str$(100)) = "100" Then ' TRUE
Debug.Print "Match"
End If</code></pre>
<h3 id="2-confusion-with-cstr">2. Confusion with <code>CStr</code></h3>
<pre><code class="language-vbnet">Dim value As Integer
value = 42
Debug.Print Str$(value) ' " 42" (with space)
Debug.Print CStr(value) ' "42" (no space)
' Know which one you need</code></pre>
<h3 id="3-no-formatting-control">3. No Formatting Control</h3>
<pre><code class="language-vbnet">Dim amount As Currency
amount = 1234.56
' Str$ gives no control
Debug.Print Str$(amount) ' " 1234.56"
' Use Format$ for currency
Debug.Print Format$(amount, "$#,##0.00") ' "$1,234.56"</code></pre>
<h3 id="4-floating-point-precision-issues">4. Floating-Point Precision Issues</h3>
<pre><code class="language-vbnet">Dim value As Double
value = 0.1 + 0.2
Debug.Print Str$(value) ' May show " 0.30000000000000004"
' Use Format$ to control precision
Debug.Print Format$(value, "0.00") ' "0.30"</code></pre>
<h3 id="5-not-handling-very-large-or-small-numbers">5. Not Handling Very Large or Small Numbers</h3>
<pre><code class="language-vbnet">Dim bigNum As Double
bigNum = 1E+20
Debug.Print Str$(bigNum) ' " 1E+20" (scientific notation)
' Be aware of scientific notation in output</code></pre>
<h3 id="6-null-values">6. Null Values</h3>
<pre><code class="language-vbnet">' Str$ cannot handle Null
Dim result As String
result = Str$(nullValue) ' Runtime error if nullValue is Null
' Check first
If Not IsNull(value) Then
result = Str$(value)
Else
result = ""
End If</code></pre>
<h2 id="practical-examples">Practical Examples</h2>
<h3 id="building-a-progress-message">Building a Progress Message</h3>
<pre><code class="language-vbnet">Function ProgressMessage(current As Long, total As Long) As String
ProgressMessage = "Processing item" & Str$(current) & _
" of" & Str$(total)
End Function
Debug.Print ProgressMessage(5, 10) ' "Processing item 5 of 10"</code></pre>
<h3 id="creating-sequential-filenames">Creating Sequential Filenames</h3>
<pre><code class="language-vbnet">Function GenerateFileName(baseNameStr As String, index As Integer) As String
GenerateFileName = baseNameStr & LTrim$(Str$(index)) & ".dat"
End Function
Dim fileName As String
fileName = GenerateFileName("data", 1) ' "data1.dat"</code></pre>
<h3 id="simple-data-export">Simple Data Export</h3>
<pre><code class="language-vbnet">Sub ExportToCSV(data() As Double, fileName As String)
Dim i As Integer
Dim lineData As String
Open fileName For Output As #1
For i = LBound(data) To UBound(data)
Print #1, LTrim$(Str$(data(i)))
Next i
Close #1
End Sub</code></pre>
<h2 id="limitations">Limitations</h2>
<ul>
<li>Always includes leading space for positive numbers (use <code>LTrim$</code> or <code>CStr</code> to remove)</li>
<li>No formatting control (no thousands separators, decimal places, etc.)</li>
<li>Cannot handle <code>Null</code> values (use <code>CStr</code> with error handling instead)</li>
<li>May produce scientific notation for very large or small numbers</li>
<li>Floating-point precision artifacts may appear in output</li>
<li>No locale-specific formatting (always uses invariant format)</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>