DisplayScript Language Reference: Types of Values

Types of Values

Numbers

Numbers are used to represent quantities like time, size, position, and color value. Write numbers using decimal notation:

show(2)
show(.07)
show(0.7)
show(-32.55)

You can manipulate numbers using the operators +, -, /, and *.

show(2 + 2)
show(2 + 2 * 7)
show((2 + 2) * 7)
show(5 / 4)

These math functions are also available: abs, atan2, ceil, cos, exp, floor, log, pow, round, sin, and sqrt. There's also max, which returns the maximum of two numbers, and min, which returns the minimum.

Numbers are represented internally in double-precision floating point. Not-a-number, or "NaN" values (like the result of 0 / 0) are not valid DisplayScript numbers: any operation that would produce a NaN fails immediately instead.

Strings

A string is an unstyled piece of text. Create a string by putting some text in double quotes "like this". If you need to put a double quote in the string itself, put a backslash before it:

"something \"in quotes\""

If you need to put a backslash in the string itself, use two backslashes:

"this will appear as a single backslash: \\"

To substitute other values into the string, use \():

var x = 2
var y = 5
var str = "x + y = \(x + y)"

In this code, str will end up with the value "x + y = 7".

Use \u{} with a hexadecimal number to specify a character by its Unicode scalar value.

show("\u{68}\u{69}")
show("\u{1f44b}")

You can apply the text function to turn a string into a drawable value.

draw text("Hello!")

The concatenate function will concatenate two strings together:

var d = "Display"
show(concatenate(d, "Script"))

Strings are also used to represent URLs. For example, to load an image:

draw centered(image("http://i.imgur.com/RIxqgj9.jpg"))

Booleans

Booleans are truth values: they can be either true or false. The operators >, <, >=, and <= produce a boolean value by comparing two numbers.

show(1 > 2)
show(1 < 2)
show(2 > 2)
show(2 >= 2)

You can use == and != to see if two values are equal or not equal to one another.

show(1 != 1)
show(7 == 3 + 4)
show("7" == "\(3 + 4)")
show([1, 2, 3] == [1, 3, 2])
show({a: 1, b: 2} == {b: 2, a: 1})

Comparing two different types of values for equality is an error. This includes the types of values inside records and arrays. Record field names must match. It is also an error to compare drawables or functions for equality.

// These equality checks all fail due to type mismatch.
show(1 == "1")
show([1] == ["1"])
show({a: 1} == {a: "1"})
show({a: 1} == {b: 1})
show(function () { return 1 } == function () { return 1 })

Use the && and || operators to combine booleans. a && b is true only when both a and b are true. Using a || b gives you the opposite: it is false only when both of its arguments are false.

show(true && false)
show(true || false)

Both of these operators "short-circuit": they only run their second parameter if necessary. That is, a && b only runs b if a is true, and a || b only runs b if a is false.

function f(str) {
    show(str)
    return true
}

true && f("1")
false && f("2")
true || f("3")
false || f("4")

Use ! (pronounced "not") to negate a boolean, turning true into false and vice versa.

show(!true)

The if statement uses a boolean to decide whether to run some code:

var num = 1
if num > 0 && num < 2 {
    show("OK")
}

See the Control Flow page for more information about if statements.

Arrays

An array is an ordered collection of values. You can make arrays using square brackets, like ["Sam", "Alex"] or [1, 1, 2, 3, 5]. An array can be empty: the empty array is written [].

To get the number of elements in an array, use the count function.

var a = [1, 2, 3]
show(count(a))

Square brackets are also used to look up particular values in an array.

var a = ["purple", "red", "yellow", "on fire"]
show(a[0])
show(a[2])

The first value in an array a is called a[0], the second value is called a[1], and so on, all the way up to a[count(a) - 1].

To append a value to the end of an array, use the append function. This function returns a new array with the value appended. The old array is left unchanged.

var a = [1, 2]
var b = append(a, 3)
show(a)
show(b)

The remove function removes a value from an array. If a value occurs more than once, remove removes only the first occurrence.

var a = [1, 2, 3]
var b = remove(a, 1)
show(a)
show(b)

You can iterate through the values in an array using a for loop.

var strings = ["first", "second", "third"]
for string in strings {
    show(string)
}

See the Control Flow page for more information about for loops.

Records

A record is a collection of labeled values, or fields. Records are written using braces {}, with each value labeled using a colon. Here's a person represented as a record:

var person = { name: "Casey Smith", age: 34, favoriteIceCreamFlavor: #chocolate }

You can look up fields in a record using the syntax record.fieldName:

var point = { x: 1, y: 7 }
show(point.x)
show(point.y)

Variants

Variants represent anything that takes one of multiple values. Variant values are denoted using a hashtag, like #this. For example, an image from the network might be #loading or #ready.

You can include a value with a variant using parentheses. If you wanted to associate some image data with the loaded image, you could use #ready(imageData), where imageData represents whatever data you want to associate with the variant.

Values associated with variants can be unpacked using the switch statement.

var loadingState = #ready("some data")
switch loadingState {
case #loading:
    draw centered(text("Loading..."))
case #ready(data):
    draw centered(text("Loaded data: \(data)"))
}

See the Control Flow page for more information about switch statements.

Functions

Functions are values which can be called with a list of arguments to yield a return value. See Functions and Drawables for more about functions.

Drawables

A drawable represents an interface element. You can draw a drawable to place the element, measure it to get its size, or ask whether it is ready. See Functions and Drawables for more about drawables in general, Measurement and Layout for more about measure, or Asynchronous Operations and Readiness for more about ready. For a full list of built in drawables, see the Drawable Function Index.

Persistent Identifiers

Persistent identifiers are used to identify state across frames. See State and Identity for more about this system.

Uncommonly-Seen Values

These kinds of values aren't seen much outside of DisplayScript's own code.

Unit Values

There is only one unit value, called __unit. Functions will return __unit if no other value is returned first.

Absolute Timestamps

Absolute timestamps represent a specific point in time. Besides comparing absolute timestamps for equality, the only operation they support is the built-in function secondsBetween, which returns a number representing the difference between the two timestamps in seconds.

You can get the absolute timestamp for the current frame using the __targetTime keyword.

If you want to get the elapsed time as a number, use the elapsedSeconds function:

show(elapsedSeconds())

Source Locations

Source locations are used as part of persistent identifiers to identify state across frames. Whenever you call a function, the source location of the call is appended to the current persistent identifier. You shouldn't need to deal with these directly.

Graphics Data

Graphics data represents platform-specific graphics objects, like images or text layout information. You can't create these objects from within a DisplayScript program: they are always created from C code and passed in.