UCASE$ / LCASE$

Syntax

Description

Converts all alphabetic characters in string$ to uppercase or lowercase respectively.

• UCASE$ — converts lowercase letters (a-z) to uppercase (A-Z). Uppercase letters and non-letters are unchanged.
• LCASE$ — converts uppercase letters (A-Z) to lowercase (a-z). Lowercase letters and non-letters are unchanged.

The conversion operates on the ASCII range [A-Za-z] only. Characters outside this range (digits, punctuation, symbols, extended ASCII, or Unicode) pass through unchanged. The original string is not modified.

Case conversion is essential for case-insensitive comparisons, normalizing user input (e.g., command keywords), formatting display text, and preparing strings for sorting or hashing where case should be ignored.

Parameters

Return Value

A new STRING with all alphabetic characters converted to the target case.

Example

FUNCTION PBMAIN() AS LONG
    LOCAL original$, result$ AS STRING
    
    original$ = "Hello World 123!"
    
    ' Convert to uppercase
    result$ = UCASE$(original$)   ' result$ = "HELLO WORLD 123!"
    PRINT "Uppercase: "; result$
    
    ' Convert to lowercase
    result$ = LCASE$(original$)   ' result$ = "hello world 123!"
    PRINT "Lowercase: "; result$
    
    ' Non-alpha characters are unchanged
    PRINT "Digits unchanged: 123!"
    
    ' Case-insensitive comparison pattern
    original$ = "PowerBASIC"
    IF UCASE$(original$) = "POWERBASIC" THEN
        PRINT "Match (case-insensitive)"
    END IF
    
    ' Practical: normalize command input
    original$ = "  QuIt  "
    result$ = TRIM$(UCASE$(original$))  ' result$ = "QUIT"
    IF result$ = "QUIT" THEN
        PRINT "Exit command recognized"
    END IF
    
    ' Practical: proper case formatting
    original$ = "john smith"
    result$ = UCASE$(LEFT$(original$, 1)) + _
              LCASE$(MID$(original$, 2))  ' result$ = "John smith"
    PRINT "Proper case: "; result$
    
    FUNCTION = 0
END FUNCTION

Generated Assembly

; Copy source to heap, iterate byte-by-byte:
; UCASE: if 'a' <= byte <= 'z': sub byte, 32
; LCASE: if 'A' <= byte <= 'Z': add byte, 32
; Then point descriptor to result

Notes

• The conversion uses simple ASCII arithmetic: subtracting 32 converts lowercase to uppercase; adding 32 converts uppercase to lowercase. This is the standard ASCII offset between 'A' (65) and 'a' (97).
• The result is allocated on the heap to accommodate the converted string. The string descriptor is updated to point to this heap buffer.
• Only the range [A-Za-z] is affected. Extended ASCII characters (128-255), including accented letters, are NOT converted.
• For case-insensitive comparison, using UCASE$(a$) = UCASE$(b$) creates two temporary strings. For performance, consider using the Windows API lstrcmpiA via DECLARE if doing many comparisons.
• Combining TRIM$ and UCASE$ is a common pattern for normalizing user input before validation.