<!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 - ucase - String">
<title>ucase - 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> / ucase</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 UCase Function
The <code>UCase</code> function returns a String that has been converted to uppercase.</p>
<h2 id="syntax">Syntax</h2>
<pre><code class="language-vbnet">UCase(string)</code></pre>
<h2 id="parameters">Parameters</h2>
<ul>
<li><code>string</code>: Required. Any valid string expression. If <code>string</code> contains Null, Null is returned.</li>
</ul>
<h2 id="returns">Returns</h2>
<p>Returns a <code>Variant (String)</code> containing the specified string converted to uppercase. Only lowercase letters are converted to uppercase; all uppercase letters and non-letter characters remain unchanged.</p>
<h2 id="remarks">Remarks</h2>
<p>The <code>UCase</code> function converts lowercase letters to uppercase:
- <strong>Case conversion</strong>: Converts a-z to A-Z
- <strong>Non-letters unchanged</strong>: Numbers, punctuation, spaces, and symbols are not affected
- <strong>Null handling</strong>: Returns Null if the argument is Null
- <strong>Empty string</strong>: Returns empty string if argument is empty
- <strong>Locale-aware</strong>: Conversion respects current locale settings for international characters
- <strong>Unicode support</strong>: Handles Unicode characters according to locale
- <strong>Already uppercase</strong>: Characters already uppercase are unchanged
- <strong>String variant</strong>: <code>UCase</code>$ variant returns String instead of Variant</p>
<h3 id="ucase-vs-ucase"><code>UCase</code> vs <code>UCase</code>$</h3>
<ul>
<li><code>UCase</code>: Returns Variant (String) - can handle and return Null</li>
<li><code>UCase$</code>: Returns String - generates error if argument is Null</li>
<li>Best practice: Use <code>UCase$</code> when you know the string is not Null for slightly better performance</li>
</ul>
<h3 id="locale-considerations">Locale Considerations</h3>
<ul>
<li>Conversion is locale-aware for international characters</li>
<li>Turkish İ (dotted I) and ı (dotless i) handled per locale</li>
<li>German ß (eszett) may convert to SS in some contexts</li>
<li>Accented characters (é, ñ, ü, etc.) convert to uppercase equivalents</li>
</ul>
<h2 id="typical-uses">Typical Uses</h2>
<ol>
<li><strong>Case-Insensitive Comparison</strong>: Normalize strings before comparison</li>
<li><strong>User Input Normalization</strong>: Convert user input to consistent case</li>
<li><strong>Data Validation</strong>: Standardize data before validation or storage</li>
<li><strong>Display Formatting</strong>: Format text for display purposes (headings, labels)</li>
<li><strong>String Matching</strong>: Prepare strings for case-insensitive searches</li>
<li><strong>Database Queries</strong>: Normalize search terms</li>
<li><strong>File Processing</strong>: Standardize file names or extensions</li>
<li><strong>Code Generation</strong>: Create uppercase identifiers or constants</li>
</ol>
<h2 id="basic-examples">Basic Examples</h2>
<h3 id="example-1-simple-conversion">Example 1: Simple Conversion</h3>
<pre><code class="language-vbnet">Dim result As String
result = UCase("Hello World")
' result = "HELLO WORLD"
result = UCase("abc123xyz")
' result = "ABC123XYZ"
result = UCase("ALREADY UPPERCASE")
' result = "ALREADY UPPERCASE"</code></pre>
<h3 id="example-2-case-insensitive-comparison">Example 2: Case-Insensitive Comparison</h3>
<pre><code class="language-vbnet">Function EqualsIgnoreCase(str1 As String, str2 As String) As Boolean
EqualsIgnoreCase = (UCase$(str1) = UCase$(str2))
End Function
' Usage:
If EqualsIgnoreCase(userInput, "YES") Then
ProcessConfirmation
End If</code></pre>
<h3 id="example-3-normalize-user-input">Example 3: Normalize User Input</h3>
<pre><code class="language-vbnet">Sub ProcessCommand(command As String)
Select Case UCase$(Trim$(command))
Case "SAVE"
SaveData
Case "LOAD"
LoadData
Case "EXIT"
CloseApplication
Case Else
MsgBox "Unknown command"
End Select
End Sub</code></pre>
<h3 id="example-4-file-extension-check">Example 4: File Extension Check</h3>
<pre><code class="language-vbnet">Function IsImageFile(fileName As String) As Boolean
Dim ext As String
ext = UCase$(Right$(fileName, 4))
IsImageFile = (ext = ".JPG" Or ext = ".PNG" Or ext = ".GIF" Or ext = ".BMP")
End Function</code></pre>
<h2 id="common-patterns">Common Patterns</h2>
<h3 id="pattern-1-case-insensitive-string-comparison">Pattern 1: Case-Insensitive String Comparison</h3>
<pre><code class="language-vbnet">Function CompareIgnoreCase(str1 As String, str2 As String) As Boolean
CompareIgnoreCase = (UCase$(str1) = UCase$(str2))
End Function</code></pre>
<h3 id="pattern-2-normalize-database-input">Pattern 2: Normalize Database Input</h3>
<pre><code class="language-vbnet">Function NormalizeForDatabase(value As String) As String
NormalizeForDatabase = UCase$(Trim$(value))
End Function</code></pre>
<h3 id="pattern-3-case-insensitive-contains">Pattern 3: Case-Insensitive Contains</h3>
<pre><code class="language-vbnet">Function ContainsIgnoreCase(source As String, searchTerm As String) As Boolean
ContainsIgnoreCase = (InStr(UCase$(source), UCase$(searchTerm)) > 0)
End Function</code></pre>
<h3 id="pattern-4-validate-yesno-response">Pattern 4: Validate Yes/No Response</h3>
<pre><code class="language-vbnet">Function IsYesResponse(response As String) As Boolean
Dim normalized As String
normalized = UCase$(Trim$(response))
IsYesResponse = (normalized = "Y" Or normalized = "YES")
End Function</code></pre>
<h3 id="pattern-5-case-insensitive-startswith">Pattern 5: Case-Insensitive <code>StartsWith</code></h3>
<pre><code class="language-vbnet">Function StartsWithIgnoreCase(str As String, prefix As String) As Boolean
StartsWithIgnoreCase = (UCase$(Left$(str, Len(prefix))) = UCase$(prefix))
End Function</code></pre>
<h3 id="pattern-6-format-heading-text">Pattern 6: Format Heading Text</h3>
<pre><code class="language-vbnet">Function FormatHeading(text As String) As String
FormatHeading = UCase$(text)
End Function</code></pre>
<h3 id="pattern-7-normalize-array-elements">Pattern 7: Normalize Array Elements</h3>
<pre><code class="language-vbnet">Sub NormalizeArray(arr() As String)
Dim i As Long
For i = LBound(arr) To UBound(arr)
arr(i) = UCase$(arr(i))
Next i
End Sub</code></pre>
<h3 id="pattern-8-case-insensitive-search-in-array">Pattern 8: Case-Insensitive Search in Array</h3>
<pre><code class="language-vbnet">Function FindInArray(arr() As String, searchValue As String) As Long
Dim i As Long
Dim searchUpper As String
searchUpper = UCase$(searchValue)
For i = LBound(arr) To UBound(arr)
If UCase$(arr(i)) = searchUpper Then
FindInArray = i
Exit Function
End If
Next i
FindInArray = -1 ' Not found
End Function</code></pre>
<h3 id="pattern-9-create-acronym">Pattern 9: Create Acronym</h3>
<pre><code class="language-vbnet">Function CreateAcronym(phrase As String) As String
Dim words() As String
Dim i As Integer
Dim result As String
words = Split(phrase, " ")
result = ""
For i = LBound(words) To UBound(words)
If Len(words(i)) > 0 Then
result = result & UCase$(Left$(words(i), 1))
End If
Next i
CreateAcronym = result
End Function</code></pre>
<h3 id="pattern-10-safe-null-handling-comparison">Pattern 10: Safe Null-Handling Comparison</h3>
<pre><code class="language-vbnet">Function SafeCompareIgnoreCase(str1 As Variant, str2 As Variant) As Boolean
If IsNull(str1) Or IsNull(str2) Then
SafeCompareIgnoreCase = False
Else
SafeCompareIgnoreCase = (UCase(str1) = UCase(str2))
End If
End Function</code></pre>
<h2 id="advanced-usage">Advanced Usage</h2>
<h3 id="example-1-case-insensitive-dictionary-class">Example 1: Case-Insensitive Dictionary Class</h3>
<pre><code class="language-vbnet">' Class: CaseInsensitiveDictionary
' Dictionary with case-insensitive key lookup
Option Explicit
Private m_Items As Collection
Private Sub Class_Initialize()
Set m_Items = New Collection
End Sub
Public Sub Add(key As String, value As Variant)
On Error Resume Next
If IsObject(value) Then
m_Items.Add value, UCase$(key)
Else
m_Items.Add value, UCase$(key)
End If
If Err.Number <> 0 Then
Err.Raise 457, , "Key already exists: " & key
End If
End Sub
Public Function Item(key As String) As Variant
On Error Resume Next
If IsObject(m_Items(UCase$(key))) Then
Set Item = m_Items(UCase$(key))
Else
Item = m_Items(UCase$(key))
End If
If Err.Number <> 0 Then
Err.Raise 5, , "Key not found: " & key
End If
End Function
Public Function Exists(key As String) As Boolean
On Error Resume Next
Dim test As Variant
test = m_Items(UCase$(key))
Exists = (Err.Number = 0)
End Function
Public Sub Remove(key As String)
On Error Resume Next
m_Items.Remove UCase$(key)
If Err.Number <> 0 Then
Err.Raise 5, , "Key not found: " & key
End If
End Sub
Public Property Get Count() As Long
Count = m_Items.Count
End Property</code></pre>
<h3 id="example-2-string-comparison-utilities-module">Example 2: String Comparison Utilities Module</h3>
<pre><code class="language-vbnet">' Module: StringComparisonUtils
' Case-insensitive string comparison utilities
Option Explicit
Public Function EqualsIgnoreCase(str1 As String, str2 As String) As Boolean
EqualsIgnoreCase = (UCase$(str1) = UCase$(str2))
End Function
Public Function StartsWithIgnoreCase(str As String, prefix As String) As Boolean
If Len(prefix) > Len(str) Then
StartsWithIgnoreCase = False
Else
StartsWithIgnoreCase = (UCase$(Left$(str, Len(prefix))) = UCase$(prefix))
End If
End Function
Public Function EndsWithIgnoreCase(str As String, suffix As String) As Boolean
If Len(suffix) > Len(str) Then
EndsWithIgnoreCase = False
Else
EndsWithIgnoreCase = (UCase$(Right$(str, Len(suffix))) = UCase$(suffix))
End If
End Function
Public Function ContainsIgnoreCase(source As String, searchTerm As String) As Boolean
ContainsIgnoreCase = (InStr(1, source, searchTerm, vbTextCompare) > 0)
End Function
Public Function IndexOfIgnoreCase(source As String, searchTerm As String, _
Optional startPos As Long = 1) As Long
IndexOfIgnoreCase = InStr(startPos, source, searchTerm, vbTextCompare)
End Function
Public Function ReplaceIgnoreCase(source As String, findText As String, _
replaceText As String) As String
ReplaceIgnoreCase = Replace(source, findText, replaceText, 1, -1, vbTextCompare)
End Function
Public Function CompareIgnoreCase(str1 As String, str2 As String) As Integer
If UCase$(str1) < UCase$(str2) Then
CompareIgnoreCase = -1
ElseIf UCase$(str1) > UCase$(str2) Then
CompareIgnoreCase = 1
Else
CompareIgnoreCase = 0
End If
End Function</code></pre>
<h3 id="example-3-text-normalizer-class">Example 3: Text Normalizer Class</h3>
<pre><code class="language-vbnet">' Class: TextNormalizer
' Normalizes text for consistent processing
Option Explicit
Public Enum NormalizationMode
nmUpperCase = 0
nmLowerCase = 1
nmTrimmed = 2
nmUpperCaseTrimmed = 3
nmLowerCaseTrimmed = 4
End Enum
Public Function Normalize(text As String, mode As NormalizationMode) As String
Select Case mode
Case nmUpperCase
Normalize = UCase$(text)
Case nmLowerCase
Normalize = LCase$(text)
Case nmTrimmed
Normalize = Trim$(text)
Case nmUpperCaseTrimmed
Normalize = UCase$(Trim$(text))
Case nmLowerCaseTrimmed
Normalize = LCase$(Trim$(text))
Case Else
Normalize = text
End Select
End Function
Public Function NormalizeArray(arr() As String, mode As NormalizationMode) As String()
Dim result() As String
Dim i As Long
ReDim result(LBound(arr) To UBound(arr))
For i = LBound(arr) To UBound(arr)
result(i) = Normalize(arr(i), mode)
Next i
NormalizeArray = result
End Function
Public Function NormalizeForComparison(text As String) As String
' Remove extra spaces and convert to uppercase
Dim temp As String
temp = Trim$(text)
' Replace multiple spaces with single space
Do While InStr(temp, " ") > 0
temp = Replace(temp, " ", " ")
Loop
NormalizeForComparison = UCase$(temp)
End Function</code></pre>
<h3 id="example-4-command-parser-module">Example 4: Command Parser Module</h3>
<pre><code class="language-vbnet">' Module: CommandParser
' Parses and processes user commands
Option Explicit
Public Function ParseCommand(commandLine As String, command As String, _
arguments() As String) As Boolean
Dim parts() As String
Dim i As Integer
commandLine = Trim$(commandLine)
If Len(commandLine) = 0 Then
ParseCommand = False
Exit Function
End If
parts = Split(commandLine, " ")
command = UCase$(parts(0))
If UBound(parts) > 0 Then
ReDim arguments(0 To UBound(parts) - 1)
For i = 1 To UBound(parts)
arguments(i - 1) = parts(i)
Next i
Else
ReDim arguments(0 To -1) ' Empty array
End If
ParseCommand = True
End Function
Public Function IsValidCommand(command As String, validCommands() As String) As Boolean
Dim i As Long
Dim cmdUpper As String
cmdUpper = UCase$(command)
For i = LBound(validCommands) To UBound(validCommands)
If UCase$(validCommands(i)) = cmdUpper Then
IsValidCommand = True
Exit Function
End If
Next i
IsValidCommand = False
End Function
Public Function GetCommandHelp(command As String) As String
Select Case UCase$(Trim$(command))
Case "HELP"
GetCommandHelp = "Displays help information"
Case "SAVE"
GetCommandHelp = "Saves the current document"
Case "LOAD"
GetCommandHelp = "Loads a document"
Case "EXIT", "QUIT"
GetCommandHelp = "Exits the application"
Case Else
GetCommandHelp = "Unknown command"
End Select
End Function</code></pre>
<h2 id="error-handling">Error Handling</h2>
<p>The <code>UCase</code> function can raise the following errors:
- <strong>Error 13 (Type mismatch)</strong>: If argument cannot be converted to a string
- <strong>Error 94 (Invalid use of Null)</strong>: When using <code>UCase$</code> (not <code>UCase</code>) with Null argument
Note: <code>UCase</code> (without $) returns Null if passed Null, while <code>UCase$</code> raises an error.</p>
<h2 id="performance-notes">Performance Notes</h2>
<ul>
<li>Very fast string operation</li>
<li>Performance is linear O(n) with string length</li>
<li><code>UCase$</code> is slightly faster than <code>UCase</code> (returns String vs Variant)</li>
<li>Consider caching result if used multiple times with same value</li>
<li>No significant difference for short strings (< 100 characters)</li>
<li>For large-scale comparisons, convert once and cache</li>
</ul>
<h2 id="best-practices">Best Practices</h2>
<ol>
<li><strong>Use <code>UCase</code>$ when possible</strong> for better performance and type safety</li>
<li><strong>Cache conversions</strong> when comparing the same string multiple times</li>
<li><strong>Combine with Trim$</strong> when normalizing user input</li>
<li><strong>Handle Null explicitly</strong> when using <code>UCase</code> (not <code>UCase</code>$)</li>
<li><strong>Use <code>StrComp</code> for locale-aware comparison</strong> instead of manual <code>UCase</code> conversion</li>
<li><strong>Consider Option Compare Text</strong> for case-insensitive operations in entire module</li>
<li><strong>Document case-sensitivity</strong> in function comments</li>
<li><strong>Normalize early</strong> in data processing pipeline</li>
<li><strong>Use for display formatting</strong> when uppercase is needed for UI</li>
<li><strong>Avoid repeated conversion</strong> in tight loops</li>
</ol>
<h2 id="comparison-table">Comparison Table</h2>
<table>
<thead>
<tr>
<th>Function</th>
<th>Conversion</th>
<th>Returns</th>
<th>Null Handling</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>UCase</code></td>
<td>To uppercase</td>
<td>Variant (String)</td>
<td>Returns Null</td>
</tr>
<tr>
<td><code>UCase$</code></td>
<td>To uppercase</td>
<td>String</td>
<td>Error on Null</td>
</tr>
<tr>
<td><code>LCase</code></td>
<td>To lowercase</td>
<td>Variant (String)</td>
<td>Returns Null</td>
</tr>
<tr>
<td><code>LCase$</code></td>
<td>To lowercase</td>
<td>String</td>
<td>Error on Null</td>
</tr>
<tr>
<td><code>StrConv</code></td>
<td>Various</td>
<td>Variant</td>
<td>Configurable</td>
</tr>
</tbody>
</table>
<h2 id="platform-notes">Platform Notes</h2>
<ul>
<li>Available in VB6, VBA, and <code>VBScript</code></li>
<li>Behavior consistent across platforms</li>
<li>Locale-aware conversion for international characters</li>
<li>Unicode support in VBA/VB6</li>
<li>String length unchanged by conversion</li>
</ul>
<h2 id="limitations">Limitations</h2>
<ul>
<li>Cannot selectively convert parts of string (use Mid$ if needed)</li>
<li>No way to specify locale explicitly (uses system locale)</li>
<li>Cannot preserve original case information (one-way conversion)</li>
<li>Does not handle special Unicode cases (e.g., title case)</li>
<li>No built-in toggle case functionality</li>
<li>Cannot convert specific character ranges</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>