<!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 - formatcurrency - String">
<title>formatcurrency - 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> / formatcurrency</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="formatcurrency-function">FormatCurrency Function</h1>
<p>Returns an expression formatted as a currency value using the currency symbol defined in the system control panel.</p>
<h2 id="syntax">Syntax</h2>
<pre><code class="language-vbnet">FormatCurrency(expression[, numdigitsafterdecimal[, includeleadingdigit[, useparensfornegativenumbers[, groupdigits]]]])</code></pre>
<h2 id="parameters">Parameters</h2>
<ul>
<li><strong>expression</strong>: Required. Expression to be formatted.</li>
<li><strong>numdigitsafterdecimal</strong>: Optional. Numeric value indicating how many places to the right of the decimal are displayed. Default is -1, which indicates the computer's regional settings are used.</li>
<li><strong>includeleadingdigit</strong>: Optional. Tristate constant that indicates whether a leading zero is displayed for fractional values. See Settings for values.</li>
<li><strong>useparensfornegativenumbers</strong>: Optional. Tristate constant that indicates whether to place negative values within parentheses. See Settings for values.</li>
<li><strong>groupdigits</strong>: Optional. Tristate constant that indicates whether numbers are grouped using the group delimiter specified in the computer's regional settings. See Settings for values.</li>
</ul>
<h2 id="settings">Settings</h2>
<p>The includeleadingdigit, useparensfornegativenumbers, and groupdigits arguments have the following settings:
- <strong>vbTrue</strong> (-1): True
- <strong>vbFalse</strong> (0): False
- <strong>vbUseDefault</strong> (-2): Use the setting from the computer's regional settings</p>
<h2 id="return-value">Return Value</h2>
<p>Returns a <code>Variant</code> of subtype <code>String</code> containing the expression formatted as a currency value.</p>
<h2 id="remarks">Remarks</h2>
<p>The <code>FormatCurrency</code> function provides a simple way to format numbers as currency values
using the system's locale settings. It automatically applies the currency symbol, decimal
separator, thousand separator, and negative number formatting according to regional settings.
<strong>Important Characteristics:</strong>
- Uses system locale for currency symbol and formatting
- Default: 2 decimal places (from regional settings)
- Automatically adds thousand separators
- Negative numbers can be displayed with parentheses or minus sign
- Leading zeros controlled by regional settings or parameter
- Currency symbol position depends on locale (before or after amount)
- Returns empty string if expression is Null
- More convenient than <code>Format</code> for simple currency formatting
- Less flexible than <code>Format</code> for custom patterns
- Locale-aware (respects user's regional settings)</p>
<h2 id="typical-uses">Typical Uses</h2>
<ul>
<li>Display prices and monetary amounts</li>
<li>Format financial reports</li>
<li>Show invoice totals</li>
<li>Display account balances</li>
<li>Format transaction amounts</li>
<li>Create currency-formatted exports</li>
<li>Display budget figures</li>
<li>Show cost calculations</li>
</ul>
<h2 id="examples">Examples</h2>
<h3 id="basic-usage">Basic Usage</h3>
<pre><code class="language-vbnet">Dim amount As Double
amount = 1234.567
' Default formatting (2 decimal places, system settings)
Debug.Print FormatCurrency(amount) ' $1,234.57
' No decimal places
Debug.Print FormatCurrency(amount, 0) ' $1,235
' Three decimal places
Debug.Print FormatCurrency(amount, 3) ' $1,234.567
' Negative with parentheses
Debug.Print FormatCurrency(-500, , , vbTrue) ' ($500.00)</code></pre>
<h3 id="handling-negative-values">Handling Negative Values</h3>
<pre><code class="language-vbnet">Dim balance As Double
balance = -1250.50
' Default negative (with minus sign)
Debug.Print FormatCurrency(balance) ' -$1,250.50
' Parentheses for negative
Debug.Print FormatCurrency(balance, 2, , vbTrue) ' ($1,250.50)
' No parentheses (explicit)
Debug.Print FormatCurrency(balance, 2, , vbFalse) ' -$1,250.50</code></pre>
<h3 id="control-leading-digits">Control Leading Digits</h3>
<pre><code class="language-vbnet">Dim fraction As Double
fraction = 0.75
' With leading zero (default)
Debug.Print FormatCurrency(fraction) ' $0.75
' No leading zero
Debug.Print FormatCurrency(fraction, 2, vbFalse) ' $.75
' Explicit leading zero
Debug.Print FormatCurrency(fraction, 2, vbTrue) ' $0.75</code></pre>
<h2 id="common-patterns">Common Patterns</h2>
<h3 id="format-invoice-line-items">Format Invoice Line Items</h3>
<pre><code class="language-vbnet">Sub DisplayInvoiceLines(items As Collection)
Dim item As Variant
Dim total As Double
Debug.Print "Item", "Quantity", "Price", "Amount"
Debug.Print String(60, "-")
total = 0
For Each item In items
Debug.Print item.Name, _
item.Quantity, _
FormatCurrency(item.Price), _
FormatCurrency(item.Quantity * item.Price)
total = total + (item.Quantity * item.Price)
Next item
Debug.Print String(60, "-")
Debug.Print "Total:", , , FormatCurrency(total)
End Sub</code></pre>
<h3 id="format-account-balance-with-parentheses">Format Account Balance with Parentheses</h3>
<pre><code class="language-vbnet">Function FormatAccountBalance(balance As Double) As String
' Show negative balances in parentheses (accounting style)
FormatAccountBalance = FormatCurrency(balance, 2, vbTrue, vbTrue, vbTrue)
End Function
' Usage
Debug.Print FormatAccountBalance(1500) ' $1,500.00
Debug.Print FormatAccountBalance(-250.50) ' ($250.50)</code></pre>
<h3 id="create-price-display">Create Price Display</h3>
<pre><code class="language-vbnet">Function FormatPrice(price As Double, showCents As Boolean) As String
If showCents Then
FormatPrice = FormatCurrency(price, 2)
Else
FormatPrice = FormatCurrency(price, 0)
End If
End Function
' Usage
Debug.Print FormatPrice(19.99, True) ' $19.99
Debug.Print FormatPrice(19.99, False) ' $20</code></pre>
<h3 id="display-transaction-summary">Display Transaction Summary</h3>
<pre><code class="language-vbnet">Sub ShowTransactionSummary(credits As Double, debits As Double)
Dim balance As Double
Debug.Print "Transaction Summary"
Debug.Print String(40, "=")
Debug.Print "Credits: ", FormatCurrency(credits)
Debug.Print "Debits: ", FormatCurrency(debits, 2, , vbTrue)
Debug.Print String(40, "-")
balance = credits - debits
Debug.Print "Balance: ", FormatCurrency(balance, 2, , vbTrue)
End Sub</code></pre>
<h3 id="format-budget-report">Format Budget Report</h3>
<pre><code class="language-vbnet">Sub PrintBudgetReport()
Dim budgeted As Double
Dim actual As Double
Dim variance As Double
budgeted = 50000
actual = 48500
variance = actual - budgeted
Debug.Print "Budget Report"
Debug.Print String(50, "=")
Debug.Print "Budgeted:", FormatCurrency(budgeted, 0)
Debug.Print "Actual: ", FormatCurrency(actual, 0)
Debug.Print "Variance:", FormatCurrency(variance, 0, , vbTrue)
If variance < 0 Then
Debug.Print "Status: Under budget"
Else
Debug.Print "Status: Over budget"
End If
End Sub</code></pre>
<h3 id="listboxcombobox-population"><code>ListBox</code>/<code>ComboBox</code> Population</h3>
<pre><code class="language-vbnet">Sub PopulatePriceList(lstPrices As ListBox, prices() As Double)
Dim i As Long
lstPrices.Clear
For i = LBound(prices) To UBound(prices)
lstPrices.AddItem FormatCurrency(prices(i))
Next i
End Sub</code></pre>
<h3 id="format-for-database-display">Format for Database Display</h3>
<pre><code class="language-vbnet">Function GetFormattedPrice(rs As ADODB.Recordset, fieldName As String) As String
If IsNull(rs.Fields(fieldName).Value) Then
GetFormattedPrice = "N/A"
Else
GetFormattedPrice = FormatCurrency(rs.Fields(fieldName).Value)
End If
End Function</code></pre>
<h3 id="calculate-and-display-tax">Calculate and Display Tax</h3>
<pre><code class="language-vbnet">Function DisplayPriceWithTax(basePrice As Double, taxRate As Double) As String
Dim tax As Double
Dim total As Double
tax = basePrice * taxRate
total = basePrice + tax
DisplayPriceWithTax = "Price: " & FormatCurrency(basePrice) & vbCrLf & _
"Tax: " & FormatCurrency(tax) & vbCrLf & _
"Total: " & FormatCurrency(total)
End Function
' Usage
MsgBox DisplayPriceWithTax(100, 0.08)</code></pre>
<h3 id="format-payment-schedule">Format Payment Schedule</h3>
<pre><code class="language-vbnet">Sub ShowPaymentSchedule(loanAmount As Double, months As Integer, rate As Double)
Dim payment As Double
Dim i As Integer
Dim balance As Double
payment = loanAmount / months
balance = loanAmount
Debug.Print "Payment Schedule"
Debug.Print String(50, "=")
Debug.Print "Month", "Payment", "Balance"
Debug.Print String(50, "-")
For i = 1 To months
Debug.Print i, FormatCurrency(payment), FormatCurrency(balance)
balance = balance - payment
Next i
End Sub</code></pre>
<h3 id="compare-values">Compare Values</h3>
<pre><code class="language-vbnet">Function ComparePrices(price1 As Double, price2 As Double) As String
Dim difference As Double
difference = price1 - price2
ComparePrices = FormatCurrency(price1) & " vs " & FormatCurrency(price2) & _
" (Difference: " & FormatCurrency(difference, 2, , vbTrue) & ")"
End Function</code></pre>
<h3 id="shopping-cart-total">Shopping Cart Total</h3>
<pre><code class="language-vbnet">Function GetCartSummary(items As Collection) As String
Dim item As Variant
Dim subtotal As Double
Dim tax As Double
Dim shipping As Double
Dim total As Double
subtotal = 0
For Each item In items
subtotal = subtotal + (item.Price * item.Quantity)
Next item
tax = subtotal * 0.08
shipping = 5.99
total = subtotal + tax + shipping
GetCartSummary = "Subtotal: " & FormatCurrency(subtotal) & vbCrLf & _
"Tax: " & FormatCurrency(tax) & vbCrLf & _
"Shipping: " & FormatCurrency(shipping) & vbCrLf & _
"Total: " & FormatCurrency(total)
End Function</code></pre>
<h2 id="advanced-usage">Advanced Usage</h2>
<h3 id="flexible-currency-formatter">Flexible Currency Formatter</h3>
<pre><code class="language-vbnet">Function FormatCurrencyEx(amount As Double, _
Optional decimals As Integer = 2, _
Optional useParens As Boolean = True, _
Optional useGroups As Boolean = True) As String
Dim leadingDigit As VbTriState
Dim parens As VbTriState
Dim groups As VbTriState
leadingDigit = vbTrue
parens = IIf(useParens, vbTrue, vbFalse)
groups = IIf(useGroups, vbTrue, vbFalse)
FormatCurrencyEx = FormatCurrency(amount, decimals, leadingDigit, parens, groups)
End Function</code></pre>
<h3 id="multi-currency-support">Multi-Currency Support</h3>
<pre><code class="language-vbnet">Function FormatMultiCurrency(amount As Double, currencyCode As String) As String
' Simple multi-currency display (uses FormatCurrency then replaces symbol)
Dim formatted As String
formatted = FormatCurrency(amount)
Select Case UCase(currencyCode)
Case "USD"
' Keep default $ symbol
FormatMultiCurrency = formatted
Case "EUR"
FormatMultiCurrency = Replace(formatted, "$", "€")
Case "GBP"
FormatMultiCurrency = Replace(formatted, "$", "£")
Case "JPY"
FormatMultiCurrency = Replace(formatted, "$", "¥")
FormatMultiCurrency = Replace(FormatMultiCurrency, ".00", "")
Case Else
FormatMultiCurrency = currencyCode & " " & Format(amount, "#,##0.00")
End Select
End Function</code></pre>
<h3 id="financial-statement-formatter">Financial Statement Formatter</h3>
<pre><code class="language-vbnet">Type FinancialLine
Description As String
Amount As Double
IsSubtotal As Boolean
End Type
Function FormatFinancialStatement(lines() As FinancialLine) As String
Dim result As String
Dim i As Long
Dim line As String
result = "Financial Statement" & vbCrLf
result = result & String(60, "=") & vbCrLf
For i = LBound(lines) To UBound(lines)
line = lines(i).Description
' Right-align amounts
line = line & Space(40 - Len(line))
line = line & FormatCurrency(lines(i).Amount, 2, vbTrue, vbTrue, vbTrue)
If lines(i).IsSubtotal Then
result = result & String(60, "-") & vbCrLf
End If
result = result & line & vbCrLf
Next i
FormatFinancialStatement = result
End Function</code></pre>
<h3 id="dynamic-precision-formatter">Dynamic Precision Formatter</h3>
<pre><code class="language-vbnet">Function FormatCurrencyDynamic(amount As Double) As String
' Use different precision based on amount magnitude
If Abs(amount) >= 1000000 Then
' Millions: no decimals
FormatCurrencyDynamic = FormatCurrency(amount, 0) & "M"
ElseIf Abs(amount) >= 1000 Then
' Thousands: no decimals
FormatCurrencyDynamic = FormatCurrency(amount, 0)
ElseIf Abs(amount) >= 1 Then
' Regular: 2 decimals
FormatCurrencyDynamic = FormatCurrency(amount, 2)
Else
' Small amounts: 4 decimals
FormatCurrencyDynamic = FormatCurrency(amount, 4)
End If
End Function</code></pre>
<h3 id="conditional-formatting">Conditional Formatting</h3>
<pre><code class="language-vbnet">Function FormatProfitLoss(amount As Double) As String
' Format with color indicators for profit/loss
If amount > 0 Then
FormatProfitLoss = "[GREEN]+" & FormatCurrency(amount)
ElseIf amount < 0 Then
FormatProfitLoss = "[RED]" & FormatCurrency(amount, 2, , vbTrue)
Else
FormatProfitLoss = "[BLACK]" & FormatCurrency(0)
End If
End Function</code></pre>
<h3 id="gridreport-alignment">Grid/Report Alignment</h3>
<pre><code class="language-vbnet">Function FormatCurrencyAligned(amount As Double, width As Integer) As String
Dim formatted As String
formatted = FormatCurrency(amount, 2, vbTrue, vbTrue, vbTrue)
' Right-align in field
If Len(formatted) < width Then
FormatCurrencyAligned = Space(width - Len(formatted)) & formatted
Else
FormatCurrencyAligned = formatted
End If
End Function</code></pre>
<h2 id="error-handling">Error Handling</h2>
<pre><code class="language-vbnet">Function SafeFormatCurrency(value As Variant, _
Optional decimals As Integer = 2) As String
On Error GoTo ErrorHandler
If IsNull(value) Then
SafeFormatCurrency = "N/A"
ElseIf Not IsNumeric(value) Then
SafeFormatCurrency = "Invalid"
Else
SafeFormatCurrency = FormatCurrency(CDbl(value), decimals)
End If
Exit Function
ErrorHandler:
Select Case Err.Number
Case 13 ' Type mismatch
SafeFormatCurrency = "Type Error"
Case 6 ' Overflow
SafeFormatCurrency = "Overflow"
Case Else
SafeFormatCurrency = "Error"
End Select
End Function</code></pre>
<h3 id="common-errors">Common Errors</h3>
<ul>
<li><strong>Error 13</strong> (Type Mismatch): Expression cannot be converted to numeric</li>
<li><strong>Error 6</strong> (Overflow): Value too large for <code>Double</code></li>
<li><strong>Error 5</strong> (Invalid procedure call): Invalid decimal places parameter</li>
</ul>
<h2 id="performance-considerations">Performance Considerations</h2>
<ul>
<li><code>FormatCurrency</code> is fast for simple formatting</li>
<li>Slightly slower than <code>Format</code> for custom patterns</li>
<li>Faster than building format strings manually</li>
<li>Locale lookups cached by system</li>
<li>Avoid repeated calls in tight loops if possible</li>
<li>Consider caching formatted values for display</li>
</ul>
<h2 id="best-practices">Best Practices</h2>
<h3 id="use-formatcurrency-for-user-facing-amounts">Use <code>FormatCurrency</code> for User-Facing Amounts</h3>
<pre><code class="language-vbnet">' Good - Locale-aware, user-friendly
lblPrice.Caption = FormatCurrency(price)
' Less portable - Hard-coded format
lblPrice.Caption = "$" & Format(price, "0.00")</code></pre>
<h3 id="handle-null-values">Handle <code>Null</code> Values</h3>
<pre><code class="language-vbnet">' Good - Check for Null
If Not IsNull(amount) Then
formatted = FormatCurrency(amount)
Else
formatted = "N/A"
End If</code></pre>
<h3 id="be-consistent-with-negative-formatting">Be Consistent with Negative Formatting</h3>
<pre><code class="language-vbnet">' Good - Use same style throughout application
Const USE_PARENS = vbTrue
formatted = FormatCurrency(balance, 2, , USE_PARENS)</code></pre>
<h2 id="comparison-with-other-functions">Comparison with Other Functions</h2>
<h3 id="formatcurrency-vs-format"><code>FormatCurrency</code> vs <code>Format</code></h3>
<pre><code class="language-vbnet">' FormatCurrency - Simple, locale-aware
result = FormatCurrency(1234.56)
' Format - More control, custom patterns
result = Format(1234.56, "$#,##0.00")</code></pre>
<h3 id="formatcurrency-vs-formatnumber"><code>FormatCurrency</code> vs <code>FormatNumber</code></h3>
<pre><code class="language-vbnet">' FormatCurrency - Adds currency symbol
result = FormatCurrency(1234.56) ' $1,234.56
' FormatNumber - No currency symbol
result = FormatNumber(1234.56) ' 1,234.56</code></pre>
<h3 id="formatcurrency-vs-strcstr"><code>FormatCurrency</code> vs <code>Str</code>/<code>CStr</code></h3>
<pre><code class="language-vbnet">' FormatCurrency - Full formatting
result = FormatCurrency(1234.56) ' $1,234.56
' Str - Basic conversion, no formatting
result = Str(1234.56) ' " 1234.56"
' CStr - Basic conversion
result = CStr(1234.56) ' "1234.56"</code></pre>
<h2 id="limitations">Limitations</h2>
<ul>
<li>Uses system locale (cannot specify different locale)</li>
<li>Limited to system's currency symbol</li>
<li>Cannot customize symbol position</li>
<li>All parameters optional, making errors less obvious</li>
<li>Tristate parameters can be confusing</li>
<li>No built-in rounding mode control</li>
<li>Cannot format multiple currencies in same session</li>
</ul>
<h2 id="regional-settings-impact">Regional Settings Impact</h2>
<p>The <code>FormatCurrency</code> function behavior varies by locale:
- <strong>United States</strong>: $1,234.56
- <strong>United Kingdom</strong>: £1,234.56
- <strong>European Union</strong>: €1.234,56 (note decimal/thousand separators)
- <strong>Japan</strong>: ¥1,235 (typically no decimal places)</p>
<h2 id="related-functions">Related Functions</h2>
<ul>
<li><code>Format</code>: More flexible formatting with custom patterns</li>
<li><code>FormatNumber</code>: Format numbers without currency symbol</li>
<li><code>FormatPercent</code>: Format numbers as percentages</li>
<li><code>FormatDateTime</code>: Format date/time values</li>
<li><code>CCur</code>: Convert expression to <code>Currency</code> type</li>
<li><code>CDbl</code>: Convert expression to <code>Double</code> type</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>