ucase - String - VB6Parse Library Reference

VB6 UCase Function

The UCase function returns a String that has been converted to uppercase.

Syntax

UCase(string)

Parameters

string: Required. Any valid string expression. If string contains Null, Null is returned.

Returns

Returns a Variant (String) containing the specified string converted to uppercase. Only lowercase letters are converted to uppercase; all uppercase letters and non-letter characters remain unchanged.

Remarks

The UCase function converts lowercase letters to uppercase:

Case conversion: Converts a-z to A-Z
Non-letters unchanged: Numbers, punctuation, spaces, and symbols are not affected
Null handling: Returns Null if the argument is Null
Empty string: Returns empty string if argument is empty
Locale-aware: Conversion respects current locale settings for international characters
Unicode support: Handles Unicode characters according to locale
Already uppercase: Characters already uppercase are unchanged
String variant: UCase$ variant returns String instead of Variant

`UCase` vs `UCase`$

UCase: Returns Variant (String) - can handle and return Null
UCase$: Returns String - generates error if argument is Null
Best practice: Use UCase$ when you know the string is not Null for slightly better performance

Locale Considerations

Conversion is locale-aware for international characters
Turkish İ (dotted I) and ı (dotless i) handled per locale
German ß (eszett) may convert to SS in some contexts
Accented characters (é, ñ, ü, etc.) convert to uppercase equivalents

Typical Uses

Case-Insensitive Comparison: Normalize strings before comparison
User Input Normalization: Convert user input to consistent case
Data Validation: Standardize data before validation or storage
Display Formatting: Format text for display purposes (headings, labels)
String Matching: Prepare strings for case-insensitive searches
Database Queries: Normalize search terms
File Processing: Standardize file names or extensions
Code Generation: Create uppercase identifiers or constants

Basic Examples

Example 1: Simple Conversion

Dim result As String

result = UCase("Hello World")
' result = "HELLO WORLD"

result = UCase("abc123xyz")
' result = "ABC123XYZ"

result = UCase("ALREADY UPPERCASE")
' result = "ALREADY UPPERCASE"

Example 2: Case-Insensitive Comparison

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

Example 3: Normalize User Input

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

Example 4: File Extension Check

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

Common Patterns

Pattern 1: Case-Insensitive String Comparison

Function CompareIgnoreCase(str1 As String, str2 As String) As Boolean
CompareIgnoreCase = (UCase$(str1) = UCase$(str2))
End Function

Pattern 2: Normalize Database Input

Function NormalizeForDatabase(value As String) As String
NormalizeForDatabase = UCase$(Trim$(value))
End Function

Pattern 3: Case-Insensitive Contains

Function ContainsIgnoreCase(source As String, searchTerm As String) As Boolean
ContainsIgnoreCase = (InStr(UCase$(source), UCase$(searchTerm)) > 0)
End Function

Pattern 4: Validate Yes/No Response

Function IsYesResponse(response As String) As Boolean
Dim normalized As String
normalized = UCase$(Trim$(response))
IsYesResponse = (normalized = "Y" Or normalized = "YES")
End Function

Pattern 5: Case-Insensitive `StartsWith`

Function StartsWithIgnoreCase(str As String, prefix As String) As Boolean
StartsWithIgnoreCase = (UCase$(Left$(str, Len(prefix))) = UCase$(prefix))
End Function

Pattern 6: Format Heading Text

Function FormatHeading(text As String) As String
FormatHeading = UCase$(text)
End Function

Pattern 7: Normalize Array Elements

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

Pattern 8: Case-Insensitive Search in Array

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

Pattern 9: Create Acronym

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

Pattern 10: Safe Null-Handling Comparison

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

Advanced Usage

Example 1: Case-Insensitive Dictionary Class

' 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

Example 2: String Comparison Utilities Module

' 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

Example 3: Text Normalizer Class

' 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

Example 4: Command Parser Module

' 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

Error Handling

The UCase function can raise the following errors:

Error 13 (Type mismatch): If argument cannot be converted to a string
Error 94 (Invalid use of Null): When using UCase$ (not UCase) with Null argument

Note: UCase (without $) returns Null if passed Null, while UCase$ raises an error.

Performance Notes

Very fast string operation
Performance is linear O(n) with string length
UCase$ is slightly faster than UCase (returns String vs Variant)
Consider caching result if used multiple times with same value
No significant difference for short strings (< 100 characters)
For large-scale comparisons, convert once and cache

Best Practices

Use UCase$ when possible for better performance and type safety
Cache conversions when comparing the same string multiple times
Combine with Trim$ when normalizing user input
Handle Null explicitly when using UCase (not UCase$)
Use StrComp for locale-aware comparison instead of manual UCase conversion
Consider Option Compare Text for case-insensitive operations in entire module
Document case-sensitivity in function comments
Normalize early in data processing pipeline
Use for display formatting when uppercase is needed for UI
Avoid repeated conversion in tight loops

Comparison Table

Function	Conversion	Returns	Null Handling
`UCase`	To uppercase	Variant (String)	Returns Null
`UCase$`	To uppercase	String	Error on Null
`LCase`	To lowercase	Variant (String)	Returns Null
`LCase$`	To lowercase	String	Error on Null
`StrConv`	Various	Variant	Configurable

Platform Notes

Available in VB6, VBA, and VBScript
Behavior consistent across platforms
Locale-aware conversion for international characters
Unicode support in VBA/VB6
String length unchanged by conversion

Limitations

Cannot selectively convert parts of string (use Mid$ if needed)
No way to specify locale explicitly (uses system locale)
Cannot preserve original case information (one-way conversion)
Does not handle special Unicode cases (e.g., title case)
No built-in toggle case functionality
Cannot convert specific character ranges