<!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 - lcase - String">
<title>lcase - 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> / lcase</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="lcase-function">LCase Function</h1>
<p>Returns a <code>String</code> that has been converted to lowercase.</p>
<h2 id="syntax">Syntax</h2>
<pre><code class="language-vbnet">LCase(string)</code></pre>
<h2 id="parameters">Parameters</h2>
<ul>
<li><code>string</code> (Required): Any valid string expression</li>
<li>If string contains <code>Null</code>, <code>Null</code> is returned</li>
</ul>
<h2 id="return-value">Return Value</h2>
<p>Returns a <code>String</code>:
- Contains the same string with all uppercase letters converted to lowercase
- Lowercase letters and non-alphabetic characters are unchanged
- Returns <code>Null</code> if string argument is <code>Null</code>
- Empty string returns empty string
- Only affects A-Z characters (not accented characters in some locales)
- Numbers, punctuation, and symbols are unchanged
- Whitespace is preserved</p>
<h2 id="remarks">Remarks</h2>
<p>The <code>LCase</code> function converts uppercase letters to lowercase:
- Only affects uppercase letters A-Z
- All other characters remain unchanged
- Counterpart to <code>UCase</code> function (converts to uppercase)
- <code>Null</code> propagates through the function (<code>Null</code> input returns <code>Null</code>)
- Does not modify the original string (strings are immutable in VB6)
- Locale-aware in some versions (may affect accented characters)
- Common for case-insensitive string comparisons
- Useful for normalizing user input
- Works with string variables, literals, and expressions
- Can be combined with other string functions (<code>Trim</code>, <code>Replace</code>, etc.)
- Performance is generally fast for typical strings
- For single character, consider using <code>LCase$</code> for slightly better performance
- <code>LCase$</code> variant returns <code>String</code> type (not <code>Variant</code>)</p>
<h2 id="typical-uses">Typical Uses</h2>
<ol>
<li><strong>Case-Insensitive Comparison</strong>: Compare strings ignoring case</li>
<li><strong>User Input Normalization</strong>: Convert user input to consistent case</li>
<li><strong>File Path Comparison</strong>: Compare file paths case-insensitively (on Windows)</li>
<li><strong>Search Operations</strong>: Case-insensitive text searching</li>
<li><strong>Data Validation</strong>: Normalize data for validation</li>
<li><strong>Database Queries</strong>: Prepare strings for case-insensitive matching</li>
<li><strong>Email Addresses</strong>: Normalize email addresses to lowercase</li>
<li><strong>Configuration Keys</strong>: Standardize configuration key format</li>
</ol>
<h2 id="basic-usage-examples">Basic Usage Examples</h2>
<pre><code class="language-vbnet">' Example 1: Basic lowercase conversion
Dim result As String
result = LCase("HELLO") ' "hello"
result = LCase("Hello World") ' "hello world"
result = LCase("VB6 Programming") ' "vb6 programming"
' Example 2: Case-insensitive comparison
Dim input As String
input = "Yes"
If LCase(input) = "yes" Then
MsgBox "User answered yes"
End If
' Example 3: Mixed case preservation
Dim text As String
text = "Hello123WORLD"
Debug.Print LCase(text) ' "hello123world" - numbers unchanged
' Example 4: Null handling
Dim value As Variant
value = Null
Debug.Print IsNull(LCase(value)) ' True - Null propagates</code></pre>
<h2 id="common-patterns">Common Patterns</h2>
<pre><code class="language-vbnet">' Pattern 1: Case-insensitive string comparison
Function EqualsIgnoreCase(str1 As String, str2 As String) As Boolean
EqualsIgnoreCase = (LCase(str1) = LCase(str2))
End Function
' Pattern 2: Case-insensitive contains check
Function ContainsIgnoreCase(text As String, searchFor As String) As Boolean
ContainsIgnoreCase = (InStr(1, LCase(text), LCase(searchFor)) > 0)
End Function
' Pattern 3: Normalize user input
Function NormalizeInput(userInput As String) As String
NormalizeInput = LCase(Trim(userInput))
End Function
' Pattern 4: Validate yes/no input
Function IsYes(input As String) As Boolean
Select Case LCase(Trim(input))
Case "yes", "y", "true", "1"
IsYes = True
Case Else
IsYes = False
End Select
End Function
' Pattern 5: Case-insensitive array search
Function FindInArray(arr As Variant, searchValue As String) As Long
Dim i As Long
Dim searchLower As String
FindInArray = -1
If Not IsArray(arr) Then Exit Function
searchLower = LCase(searchValue)
For i = LBound(arr) To UBound(arr)
If LCase(arr(i)) = searchLower Then
FindInArray = i
Exit Function
End If
Next i
End Function
' Pattern 6: Extract lowercase letters only
Function GetLowercaseLetters(text As String) As String
Dim i As Long
Dim char As String
Dim result As String
result = ""
For i = 1 To Len(text)
char = Mid(text, i, 1)
If char = LCase(char) And char >= "a" And char <= "z" Then
result = result & char
End If
Next i
GetLowercaseLetters = result
End Function
' Pattern 7: Normalize email address
Function NormalizeEmail(email As String) As String
NormalizeEmail = LCase(Trim(email))
End Function
' Pattern 8: Case-insensitive Replace
Function ReplaceIgnoreCase(text As String, findStr As String, _
replaceStr As String) As String
Dim pos As Long
Dim result As String
Dim textLower As String
Dim findLower As String
result = text
textLower = LCase(text)
findLower = LCase(findStr)
pos = InStr(1, textLower, findLower)
Do While pos > 0
result = Left(result, pos - 1) & replaceStr & _
Mid(result, pos + Len(findStr))
textLower = LCase(result)
pos = InStr(pos + Len(replaceStr), textLower, findLower)
Loop
ReplaceIgnoreCase = result
End Function
' Pattern 9: Check if string is all lowercase
Function IsAllLowercase(text As String) As Boolean
IsAllLowercase = (text = LCase(text))
End Function
' Pattern 10: Toggle case
Function ToggleCase(text As String) As String
Dim i As Long
Dim char As String
Dim result As String
result = ""
For i = 1 To Len(text)
char = Mid(text, i, 1)
If char = UCase(char) Then
result = result & LCase(char)
Else
result = result & UCase(char)
End If
Next i
ToggleCase = result
End Function</code></pre>
<h2 id="advanced-usage-examples">Advanced Usage Examples</h2>
<pre><code class="language-vbnet">' Example 1: Case-insensitive dictionary/lookup
Public Class CaseInsensitiveDictionary
Private m_dict As Object ' Scripting.Dictionary
Private Sub Class_Initialize()
Set m_dict = CreateObject("Scripting.Dictionary")
m_dict.CompareMode = vbTextCompare ' Alternative to LCase
End Sub
Public Sub Add(key As String, value As Variant)
Dim keyLower As String
keyLower = LCase(key)
If m_dict.Exists(keyLower) Then
Err.Raise 457, "CaseInsensitiveDictionary", "Key already exists"
End If
If IsObject(value) Then
Set m_dict(keyLower) = value
Else
m_dict(keyLower) = value
End If
End Sub
Public Function Get(key As String) As Variant
Dim keyLower As String
keyLower = LCase(key)
If Not m_dict.Exists(keyLower) Then
Err.Raise 5, "CaseInsensitiveDictionary", "Key not found"
End If
If IsObject(m_dict(keyLower)) Then
Set Get = m_dict(keyLower)
Else
Get = m_dict(keyLower)
End If
End Function
Public Function Exists(key As String) As Boolean
Exists = m_dict.Exists(LCase(key))
End Function
Public Sub Remove(key As String)
m_dict.Remove LCase(key)
End Sub
End Class
' Example 2: Text search with case-insensitive highlighting
Public Class TextHighlighter
Public Function Highlight(text As String, searchTerm As String, _
highlightStart As String, _
highlightEnd As String) As String
Dim result As String
Dim pos As Long
Dim lastPos As Long
Dim textLower As String
Dim searchLower As String
If Len(searchTerm) = 0 Then
Highlight = text
Exit Function
End If
result = ""
lastPos = 1
textLower = LCase(text)
searchLower = LCase(searchTerm)
pos = InStr(lastPos, textLower, searchLower)
Do While pos > 0
' Add text before match
result = result & Mid(text, lastPos, pos - lastPos)
' Add highlighted match
result = result & highlightStart & _
Mid(text, pos, Len(searchTerm)) & highlightEnd
lastPos = pos + Len(searchTerm)
pos = InStr(lastPos, textLower, searchLower)
Loop
' Add remaining text
result = result & Mid(text, lastPos)
Highlight = result
End Function
End Class
' Example 3: String matcher with wildcards
Public Class WildcardMatcher
Public Function Matches(text As String, pattern As String, _
Optional caseSensitive As Boolean = False) As Boolean
Dim textToMatch As String
Dim patternToMatch As String
If caseSensitive Then
textToMatch = text
patternToMatch = pattern
Else
textToMatch = LCase(text)
patternToMatch = LCase(pattern)
End If
Matches = MatchesInternal(textToMatch, patternToMatch)
End Function
Private Function MatchesInternal(text As String, pattern As String) As Boolean
' Simple wildcard matching (* = any chars, ? = any single char)
If pattern = "*" Then
MatchesInternal = True
Exit Function
End If
If Len(pattern) = 0 Then
MatchesInternal = (Len(text) = 0)
Exit Function
End If
If Left(pattern, 1) = "*" Then
' Try matching rest of pattern at various positions
Dim i As Long
For i = 0 To Len(text)
If MatchesInternal(Mid(text, i + 1), Mid(pattern, 2)) Then
MatchesInternal = True
Exit Function
End If
Next i
MatchesInternal = False
ElseIf Left(pattern, 1) = "?" Then
If Len(text) > 0 Then
MatchesInternal = MatchesInternal(Mid(text, 2), Mid(pattern, 2))
Else
MatchesInternal = False
End If
Else
If Len(text) > 0 And Left(text, 1) = Left(pattern, 1) Then
MatchesInternal = MatchesInternal(Mid(text, 2), Mid(pattern, 2))
Else
MatchesInternal = False
End If
End If
End Function
End Class
' Example 4: Command parser with case-insensitive commands
Public Class CommandParser
Private m_commands As Collection
Private Sub Class_Initialize()
Set m_commands = New Collection
End Sub
Public Sub RegisterCommand(commandName As String, handler As Object)
m_commands.Add handler, LCase(commandName)
End Sub
Public Function Parse(input As String) As Boolean
Dim parts() As String
Dim command As String
Dim handler As Object
Parse = False
input = Trim(input)
If Len(input) = 0 Then Exit Function
parts = Split(input, " ")
If UBound(parts) < 0 Then Exit Function
command = LCase(parts(0))
On Error Resume Next
Set handler = m_commands(command)
On Error GoTo 0
If Not handler Is Nothing Then
' Execute command handler
' handler.Execute(parts)
Parse = True
End If
End Function
Public Function GetCommandList() As String
Dim i As Long
Dim result As String
result = ""
For i = 1 To m_commands.Count
If i > 1 Then result = result & ", "
' Note: Can't easily get key from Collection
' This is simplified example
Next i
GetCommandList = result
End Function
End Class</code></pre>
<h2 id="error-handling">Error Handling</h2>
<p><code>LCase</code> handles special cases gracefully:</p>
<pre><code class="language-vbnet">' Empty string returns empty string
Debug.Print LCase("") ' ""
' Null propagates
Dim value As Variant
value = Null
Debug.Print IsNull(LCase(value)) ' True
' Non-alphabetic characters unchanged
Debug.Print LCase("123!@#") ' "123!@#"
' Mixed content
Debug.Print LCase("ABC123xyz") ' "abc123xyz"
' Safe pattern with Null check
Function SafeLCase(value As Variant) As String
If IsNull(value) Then
SafeLCase = ""
Else
SafeLCase = LCase(value)
End If
End Function</code></pre>
<h2 id="performance-considerations">Performance Considerations</h2>
<ul>
<li><strong>Fast Operation</strong>: <code>LCase</code> is generally very fast</li>
<li><strong>String Creation</strong>: Creates new string (strings are immutable)</li>
<li><strong>Repeated Calls</strong>: Cache result if using same lowercase value multiple times</li>
<li><strong><code>LCase$</code> Variant</strong>: Use <code>LCase$</code> for <code>String</code> return type (slightly faster)
Performance tips:</li>
</ul>
<pre><code class="language-vbnet">' Less efficient - multiple conversions
If LCase(str1) = LCase(str2) And LCase(str1) = LCase(str3) Then
' More efficient - cache conversion
Dim str1Lower As String
str1Lower = LCase(str1)
If str1Lower = LCase(str2) And str1Lower = LCase(str3) Then</code></pre>
<h2 id="best-practices">Best Practices</h2>
<ol>
<li><strong>Case-Insensitive Comparisons</strong>: Always use <code>LCase</code> for both operands</li>
<li><strong>Null Handling</strong>: Check for <code>Null</code> before calling <code>LCase</code> if needed</li>
<li><strong>Cache Results</strong>: Store converted strings when used multiple times</li>
<li><strong>Database Comparisons</strong>: Use <code>LCase</code> to normalize before database queries</li>
<li><strong>User Input</strong>: Always normalize user input with <code>LCase</code> + <code>Trim</code></li>
<li><strong>Email Addresses</strong>: Convert email addresses to lowercase for storage/comparison</li>
<li><strong>File Extensions</strong>: Use <code>LCase</code> when comparing file extensions</li>
<li><strong>Configuration</strong>: Use consistent casing for configuration keys</li>
</ol>
<h2 id="comparison-with-related-functions">Comparison with Related Functions</h2>
<table>
<thead>
<tr>
<th>Function</th>
<th>Purpose</th>
<th>Returns</th>
<th>Use Case</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>LCase</code></td>
<td>Convert to lowercase</td>
<td><code>String</code></td>
<td>Lowercase conversion</td>
</tr>
<tr>
<td><code>UCase</code></td>
<td>Convert to uppercase</td>
<td><code>String</code></td>
<td>Uppercase conversion</td>
</tr>
<tr>
<td><code>StrComp</code></td>
<td>Compare strings</td>
<td><code>Integer</code></td>
<td>Case-sensitive or insensitive comparison</td>
</tr>
<tr>
<td><code>Trim</code></td>
<td>Remove whitespace</td>
<td><code>String</code></td>
<td>Cleanup whitespace</td>
</tr>
<tr>
<td><code>Left</code>/<code>Right</code>/<code>Mid</code></td>
<td>Extract substring</td>
<td><code>String</code></td>
<td>Substring extraction</td>
</tr>
</tbody>
</table>
<h2 id="lcase-vs-strcomp"><code>LCase</code> vs <code>StrComp</code></h2>
<pre><code class="language-vbnet">Dim str1 As String, str2 As String
str1 = "Hello"
str2 = "HELLO"
' Using LCase for comparison
If LCase(str1) = LCase(str2) Then
MsgBox "Equal (case-insensitive)"
End If
' Using StrComp for comparison
If StrComp(str1, str2, vbTextCompare) = 0 Then
MsgBox "Equal (case-insensitive)"
End If
' LCase is more explicit and readable for simple comparisons
' StrComp is better when you need the comparison result (-1, 0, 1)</code></pre>
<h2 id="lcase-variant"><code>LCase$</code> Variant</h2>
<pre><code class="language-vbnet">' LCase returns Variant
Dim result As Variant
result = LCase("HELLO")
' LCase$ returns String (slightly faster, cannot handle Null)
Dim resultStr As String
resultStr = LCase$("HELLO")
' LCase$ will error on Null
' resultStr = LCase$(Null) ' Error 94: Invalid use of Null</code></pre>
<h2 id="platform-and-version-notes">Platform and Version Notes</h2>
<ul>
<li>Available in all VB6 versions</li>
<li>Part of VBA core functions</li>
<li>Returns <code>Variant</code> containing <code>String</code> (<code>LCase$</code> returns <code>String</code> type)</li>
<li>Locale-aware in some implementations</li>
<li>Only converts A-Z in most locales</li>
<li>Accented characters may or may not be converted depending on locale</li>
</ul>
<h2 id="limitations">Limitations</h2>
<ul>
<li>Only converts standard ASCII uppercase letters (A-Z)</li>
<li>Accented characters may not be converted consistently</li>
<li>Does not handle Unicode case mapping comprehensively</li>
<li>Cannot convert specific ranges of characters</li>
<li>No option to preserve certain characters</li>
<li>Creates new string (cannot modify in place)</li>
</ul>
<h2 id="related-functions">Related Functions</h2>
<ul>
<li><code>UCase</code>: Convert string to uppercase</li>
<li><code>StrComp</code>: Compare strings with case options</li>
<li><code>Trim</code>/<code>LTrim</code>/<code>RTrim</code>: Remove whitespace</li>
<li><code>Replace</code>: Replace substrings (with case-sensitive option)</li>
<li><code>InStr</code>: Find substring (can be case-insensitive)</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>