Skip to main content

Select Case Statement

The select case statement runs one block of code out of several, based on the value of an expression. It's BrighterScript's version of a switch statement. The syntax borrows from Visual Basic, since BrightScript itself is heavily based on VB.

A select case always transpiles to a plain if/else if/else chain, so it works on every Roku device.

Basic usage​

sub describe(numericValue)
    select case numericValue
        case 1
            print "one"
        case 6, 7, 8
            print "between 6 and 8, inclusive"
        case else
            print "no matching case"
    end select
end sub
View the transpiled BrightScript code
sub describe(numericValue)
    if numericValue = 1 then
        print "one"
    else if numericValue = 6 or numericValue = 7 or numericValue = 8 then
        print "between 6 and 8, inclusive"
    else
        print "no matching case"
    end if
end sub

The cases are checked from top to bottom, and only the first matching case runs. If nothing matches, the case else branch runs. If there's no case else, nothing runs.

Syntax​

select [case] testExpression
[case valueList
[statements]]
[case else
[elseStatements]]
end select
  • testExpression (the "subject") is any expression: a variable, a literal, a function call, m.top.someField, and so on.
  • valueList is one or more comma-separated expressions. The case matches if the subject equals any of them.
  • case else is optional. It must come last, and there can only be one.
  • end select can also be written as endselect. Like the rest of BrightScript, the keywords are case-insensitive (Select Case, End Select, and so on).

No fallthrough​

If you're coming from C, Java, or JavaScript, this is the big difference: cases never fall through, and you don't need a break statement. Once a case body finishes, execution continues after end select. (To leave a case early, use exit select.)

To run the same code for several values, list them together in one case:

select case key
    case "left", "right"
        m.moveHorizontally(key)
    case "up", "down"
        m.moveVertically(key)
end select

An empty case doesn't run the next case's body. It just does nothing. Since that's almost always a mistake, BrighterScript flags it:

select case key
    case "left"   ' warning: empty case does nothing (it does NOT fall through to "right")
    case "right"
        m.moveHorizontally(key)
    case else
end select

If you really do want a case that does nothing, put a comment or an exit select in it. Either one tells the compiler it's on purpose:

select case key
    case "back"
        ' handled by the parent screen
    case "options"
        exit select
    case "OK"
        m.select()
    case else
end select

In the single-line form, a comment would hide the rest of the line, so use exit select:

select case key : case "back" : exit select : case "OK" : m.select() : end select

Values on multiple lines​

Long value lists can be split across lines. Each line except the last must end with a comma:

select case errorCode
    case 401,
        403,
        407
        showLoginScreen()
    case else
        showGenericError()
end select

The values can also start on the line after case:

select case errorCode
    case
        401, 403, 407
        showLoginScreen()
    case else
        showGenericError()
end select

The next line is only treated as the value list when the entire line is a comma-separated list of expressions. If it's anything else (like print "x", another case, or end select), you'll get an error that the case has no value. Keep in mind that a function call or a comparison (like doSomething() or a = b) is a valid value, so a case whose value was accidentally left off will use its first body line as the value.

Single-line form​

Use : to separate statements, like everywhere else in BrightScript:

select case x : case 1 : print "one" : case else : print "other" : end select

select case x
    case 1: print "one"
    case 2: print "two"
    case else: print "other"
end select

A select case can also be used inside a single-line if:

if isReady then select case x : case 1 : print "one" : case else : print "other" : end select else print "not ready"

select case true​

A common VB idiom is to select on true and use a condition for each case. The first case whose condition is true runs. BrighterScript recognizes this pattern and emits the conditions directly:

select case true
    case age < 13
        print "child"
    case age < 20
        print "teenager"
    case else
        print "adult"
end select
View the transpiled BrightScript code
if age < 13 then
    print "child"
else if age < 20 then
    print "teenager"
else
    print "adult"
end if

The subject is evaluated only once​

The subject is evaluated a single time, no matter how many cases there are. When the subject is a local variable or a literal, BrighterScript uses it directly. Anything else (function calls, m.something, array lookups, etc.) is stored in a temporary variable first. That way a function isn't called once per case, and a node field isn't read over and over:

select case getStatus()
    case "ready"
        start()
    case "loading", "buffering"
        showSpinner()
    case else
        showError()
end select
View the transpiled BrightScript code
__bsSelectCaseSubject = getStatus()
if __bsSelectCaseSubject = "ready" then
    start()
else if __bsSelectCaseSubject = "loading" or __bsSelectCaseSubject = "buffering" then
    showSpinner()
else
    showError()
end if

The same __bsSelectCaseSubject variable is reused, even for nested select case statements. That's safe because once a case body starts running, the outer select case never reads its subject again. Just avoid naming your own variables __bsSelectCaseSubject.

How values are compared​

Each value is compared to the subject with BrightScript's = operator, so the usual BrightScript rules apply:

  • String comparisons are case-sensitive. "Up" does not match case "up". Normalize first if needed: select case lcase(key).

  • Integers and floats compare fine against each other (case 1 matches 1.0).

  • Comparing mismatched types crashes. In BrightScript, "1" = 1 is a runtime Type Mismatch error, not false. BrighterScript warns when a literal case value has a different type than the subject or the other literal values:

    select case 1
        case "1" ' warning: comparing a string against a number crashes at runtime
    end select

    BrighterScript can only catch this with literal values. If your subject might hold different types at runtime, check the type first (i.e. select case type(value)).

Values can be any expression, not just literals. Values that contain their own comparison or logical operators are wrapped in parentheses so they keep their meaning. For example, case a and b becomes subject = (a and b).

Enums and constants​

Enums and constants work as case values (or as the subject) and are replaced with their literal values in the output, like they are everywhere else:

enum Direction
    up = "up"
    down = "down"
end enum

sub move(direction)
    select case direction
        case Direction.up
            m.y -= 1
        case Direction.down
            m.y += 1
        case else
    end select
end sub
View the transpiled BrightScript code
sub move(direction)
    if direction = "up" then
        m.y -= 1
    else if direction = "down" then
        m.y += 1
    else
    end if
end sub

Covering every enum member​

When the subject is typed as an enum, BrighterScript knows every value it can hold. If your cases cover every member, you don't need a case else:

enum RemoteDirection
    up = "up"
    down = "down"
    left = "left"
    right = "right"
end enum

sub move(direction as RemoteDirection)
    select case direction
        case RemoteDirection.up
            m.y -= 1
        case RemoteDirection.down
            m.y += 1
        case RemoteDirection.left
            m.x -= 1
        case RemoteDirection.right
            m.x += 1
    end select
end sub

If you leave a member out, and there's no case else, you'll get a warning that names the missing members:

sub move(direction as RemoteDirection)
    ' warning: 'select case' on 'RemoteDirection' does not handle: left, right
    select case direction
        case RemoteDirection.up
            m.y -= 1
        case RemoteDirection.down
            m.y += 1
    end select
end sub

This is most useful when the enum changes. If you later add center to RemoteDirection, every select case on it that has no case else gets flagged, so you can find each one that needs a new case.

A few details:

  • A member counts as covered if it appears anywhere in a case's value list, either as RemoteDirection.up or as its literal value ("up").
  • A case else counts as handling everything, so there's no coverage warning when there is one.
  • The check only happens when the subject's type is known to come from a single enum, i.e. a parameter declared as RemoteDirection. If BrighterScript can tell the subject only holds some of the members (i.e. a local variable that was only ever assigned RemoteDirection.up or RemoteDirection.down), only those members need a case. When the type is anything else (dynamic, string, or unknown), the regular warning for a missing case else applies instead, since there's no way to list every possible value.
  • Case values that are neither a member reference nor a literal (i.e. case getDirection()) don't count as covering any member.
  • A case value from a different enum than the subject (i.e. case OtherEnum.up when the subject is a RemoteDirection) is flagged too, because it's almost always a mistake.

Variable types after a select case​

BrighterScript tracks variable types through a select case the same way it does through the if chain it becomes. A variable assigned in every case, including case else, has the new type afterward:

sub main(x as integer)
    y = 0 ' y is an integer here
    select case x
        case 1
            y = "one"
        case else
            y = "not one"
    end select
    print y ' y is a string here
end sub

If any case (or the case else) doesn't assign it, or there's no case else, the variable could still hold its old type, so it becomes a union (integer or string). A variable that's first created in only some of the cases might be uninitialized afterward.

A few details:

  • Covering every member of an enum subject still counts as having no case else here. An enum is just a string or number at runtime, so the subject could still hold some other value.
  • If a case can exit select before the end of its body (i.e. if done then exit select), the assignments after that point might not run, so they don't count as happening in every case. An exit select as the last statement in a case doesn't affect this.

Loops, exit, continue, and return​

Because a select case becomes an if statement, loop control inside a case applies to the enclosing loop, just like it would inside an if:

for each item in items
    select case item.type
        case "header"
            continue for    ' skips to the next item
        case "footer"
            exit for        ' stops the loop
        case else
            render(item)
    end select
end for

return works the same way.

exit select​

exit select leaves the select case immediately and continues after end select, like exit for and exit while do for loops:

sub onCommand(command)
    select case command
        case "save"
            if not m.isDirty then
                exit select
            end if
            m.save()
        case else
    end select
    print "done"
end sub

BrightScript has no way to leave an if early, so an exit select in the middle of a case becomes a goto to a label placed right after the generated end if. This works on every firmware version:

sub onCommand(command)
    if command = "save" then
        if not m.isDirty then
            goto BRIGHTERSCRIPT_EXIT_SELECT_0
        end if
        m.save()
    else
    end if
    BRIGHTERSCRIPT_EXIT_SELECT_0:
    print "done"
end sub

When exit select is the last statement of a case, there's nothing left to skip, so it's simply removed. That makes it a clear way to write a case that intentionally does nothing (see no fallthrough):

sub onKey(key)
    select case key
        case "back"
            ' handled by the parent screen
            exit select
        case "OK"
            m.select()
        case else
    end select
end sub
View the transpiled BrightScript code
sub onKey(key)
    if key = "back" then
        ' handled by the parent screen
    else if key = "OK" then
        m.select()
    else
    end if
end sub

The label is only generated when something jumps to it. A select case with no exit select, or whose only exit selects are at the end of a case, gets no label at all. Each select case that needs one gets its own numbered label.

exit select can't be used:

  • outside of a select case
  • inside a loop within a case (i.e. case 1 : for each item in items : exit select). Use exit for or exit while to leave the loop first.
  • inside a function defined within a case (the function has its own body, so there's no select case to exit)

In a nested select case, exit select leaves the innermost one.

The optional case keyword​

Like VB, the case right after select is optional:

select m.state
    case "idle"
        startPlayback()
    case else
end select

This short form only works when the subject starts with a variable name, a literal, or not. Writing select (x) or select -x doesn't work, because BrighterScript can't tell those apart from code that uses a variable or function named select (i.e. select(x)). When in doubt, write select case.

select, case, and endselect as names​

These words were never reserved in BrightScript, so existing code may already use them as variable, function, field, or method names. All of that still works:

select = 1
case = "upper"
m.case.select()
obj = { select: 1, case: 2 }
sub select(item)
end sub

There's one limitation. Inside a select case body, a line that starts with case is always read as the next case. Assignments like case = 1, case.name = 1, case[0] = 1, and case++ still work. But case(1) or case something at the start of a line inside a select case is read as a new case clause.

Comments​

Comments are kept in the output. A comment on the select case line, or between select case and the first case, is placed above the generated if:

select case a ' what kind of a?
    ' the most common values come first
    case 1 ' one
        print "one"
    case else
end select
View the transpiled BrightScript code
' what kind of a?
' the most common values come first
if a = 1 then ' one
    print "one"
else
end if

Only comments may appear before the first case. Any other statement there is an error.

.brs files​

select case is a BrighterScript feature, so it's only allowed in .bs files.

Not supported​

A few other VB features are not supported:

  • Range cases: case 1 to 5
  • Relational cases: case is > 5

For ranges and relational checks, use select case true with a condition:

select case true
    case score >= 90
        grade = "A"
    case score >= 80 and score < 90
        grade = "B"
    case else
        grade = "C"
end select