ArithmeticExpression

A collection of arithmetic functions and operations, which other Watch Face Format elements use to resolve real-time attribute values and gyroscopic effects.

Introduced in Wear OS 4.

Example

An example expression for rotating a value up to 5 degrees in either direction, based on the $ x $-value of the Wear OS device's accelerometer:

(5/90)*clamp([ACCELEROMETER_ANGLE_X],0,90) + (-5/90)*clamp([ACCELEROMETER_ANGLE_X],-90,0)

...which is equivalent to the following mathematical expression, where $ \theta_x $ represents the accelerometer angle in the $ x $-direction:

$$ \frac{5}{90} * max(min(\theta_x, 90), -90) $$

Functions

The Watch Face Format recognizes the following string values as functions:

Function Description Return type Availability
round() Converts the input value to a floating-point value, then performs the standard round() mathematical operation. Integer Version 1
floor() Performs the standard floor() mathematical operation. Float Version 1
ceil() Performs the standard ceil() mathematical operation. Float Version 1
fract() Returns the fractional part of the input value; that is, the part of the floating-point value that appears to the right of the decimal point. Float Version 1
sin() Performs the standard sin() trigonometric operation. Float Version 1
cos() Performs the standard cos() trigonometric operation. Float Version 1
tan() Performs the standard tan() trigonometric operation. Float Version 1
asin() Performs the standard asin() trigonometric operation. The returned value is always in the range $ [-\frac{\pi}{2}, \frac{\pi}{2}] $. Float Version 1
acos() Performs the standard acos() trigonometric operation. The returned value is always in the range $ [0.0, \pi] $. Float Version 1
atan() Performs the standard atan() trigonometric operation. The returned value is always in the range $ [-\frac{\pi}{2}, \frac{\pi}{2}] $. Float Version 1
abs() Converts the input value to a floating-point value, then performs the standard abs() mathematical operation. Float Version 1
clamp(,,) Converts the input values to floating-point values, then performs the clamp() Jetpack operation to fit the first value in the range defined by the second and third values. Float Version 1
rand(,) Generates a random floating-point value that fulfills the following conditions at the same time:
  • Greater than or equal to the first value.
  • Less than or equal to the second value.
Assumes that the first value is less than or equal to the second value. 		Float Version 1
log() Performs the standard base-$ e $ log() mathematical operation. Float Version 1
log2() Simulates a base-2 logarithm. This value is calculated by dividing the base-10 log() of the input value) by the base-10 logarithm of $ 2 $. Float Version 1
log10() Performs the standard base-10 log() mathematical operation. Float Version 1
sqrt() Performs the standard sqrt() mathematical operation. Float Version 1
cbrt() Performs the standard cbrt() mathematical operation. Float Version 1
exp() Performs the standard exp() mathematical operation. Float Version 1
expm1() Directly calls the expm1() mathematical operation if the input value is $ 1 $. For any other input value, simulates the function by performing the standard exp() mathematical operation, then subtracting 1. Float Version 1
deg() Performs the standard toDegrees() mathematical operation. $ \frac{\pi}{2} $ is defined as 90 degrees, and $ \pi $ is defined as 180 degrees. Float Version 1
rad() Performs the standard toRadians() mathematical operation. 90 degrees is defined as $ \frac{\pi}{2} $, and 180 degrees is defined as $ \pi $. Float Version 1
pow(,) Performs the standard pow() mathematical operation. The output value is always a floating-point number. Float Version 1
numberFormat(,) Applies the number format in the first value to the second value. The first value can contain the following characters:
  • # -- represents a numeric digit.
  • , -- represents a comma separator in large numbers.
  • . -- represents a decimal point.

For a full reference, see DecimalFormat.

 String Version 1
icuText()

Converts the input date format string to a pattern that matches the expected locale format. If the parent PartText element includes a Localization element, that locale's format is used. Otherwise, uses the Wear OS device's current locale.

For example, if the device is being used in the United States, an input value of EE, MMM d, yyyy h:mm a yields the following output: Tue, Mar 14, 2023 1:59 PM

 String Version 1
icuText(,)

Converts the first argument input date format string to a pattern that matches the expected locale format. The second argument is a timestamp string in milliseconds.

If the parent PartText element includes a Localization element, that locale's format is used. Otherwise, uses the Wear OS device's current locale.

 String Version 2
icuBestText()

Converts the input date format string to the current time whose pattern matches the expected format. If the parent PartText element includes a Localization element, that locale's format is used. Otherwise, uses the Wear OS device's current locale.

For example, if the device is being used in the United States on March 14, 2023 at 1:59 PM, an input value of yyyy MMM d EE a h:mm yields the following output: Tue, Mar 14, 2023, 1:59 PM

 String Version 1
icuBestText(,)

Converts the first argument input date format string to the current time whose pattern matches the expected format. The second argument is a timestamp string in milliseconds.

If the parent PartText element includes a Localization element, that locale's format is used. Otherwise, uses the Wear OS device's current locale.

 String Version 2
subText(,,)

Extracts a substring from the first value. The second value indicates the 0-based index into the first value where the substring should begin. The third value indicates the 0-based index into the first value where substring extraction should stop ("from the second value up to, but not including, the third value").

Examples:
  • subText("abc def", 2, 5) is c d
  • subText("abc def", 2, 7) is c def
 String Version 1
textLength()

Calculates the length of the input string.

Examples:
  • textLength("") is 0
  • textLength("abcdef") is 6
 String Version 1
colorRgb(,,)

Calculates a color value from RGB values

Examples:
  • colorRgb(255,0,0) is the color red.
 Color Version 4
colorArgb(,,)

Calculates a color value from ARGB values

Examples:
  • colorRgb(128,255,0,0) is the color red, with 50% opacity.
 Color Version 4
extractColorFromColors(,,)

Extracts a color from a list of colors. The function takes three arguments:

  • List of color hex values
  • Whether to interpolate the resulting color
  • The value to be converted, in the range 0.0 - 1.0

Examples:
  • extractColorFromColors("FF0000 00FF00 0000FF", false, 0.2) is the color red.
  • extractColorFromColors( [COMPLICATION.GOAL_PROGRESS_COLORS], [COMPLICATION.GOAL_PROGRESS_COLOR_INTERPOLATE], [COMPLICATION.GOAL_PROGRESS_VALUE] / [COMPLICATION.GOAL_PROGRESS_TARGET_VALUE] ) is the color taken from a list supplied by a Goal Complication.
 Color Version 4
extractColorFromWeightedColors(,,)

Extracts a color from a list of colors. The function takes four arguments:

  • List of color hex values
  • Corresponding list of weights for each color
  • Whether to interpolate the resulting color
  • The value to be converted, in the range 0.0 - 1.0
Examples:
  • extractColorFromWeightedColors( #97d700 #FCE300 #ff8200 #f65058 #9461c9, 3 3 2 3 1, false, 0.1) is the color represented by #97d700
 Color Version 4

Operators

The Watch Face Format recognizes the following string values as operators:

+
Unary plus, or addition of multiple values. Supports both integers and floating-point values.
-
Unary minus, or subtraction of multiple values. Supports both integers and floating-point values.
*
Multiplication of multiple integer or floating-point values.
/

Division of 2 integer or floating-point values.

If division of 2 integers results in a non-integer value, the decimal part is preserved in the floating-point result. For example, $ \frac{1}{2} = 0.5 $.

In addition, the expression $ \frac{x}{0} $ is evaluated as 0, where $ x $ is any integer.

%

Modular division of 2 integer or floating-point values.

If both operands are integers, the result is the remainder from dividing the 2 values. For example, $ 19 \bmod 7 = 5 $.

If at least one operand is a floating-point number, the result is a floating-point equivalent of the remainder; for example: $ 19.0 \bmod 7 = 5.0 $.

~

Bitwise "not" operator. Several examples:

  • ~1 is $ -2 $
  • ~0 is $ -1 $
!

Logical "not" operator, which supports double negatives. Several examples:

  • $ !2 $ is false
  • $ !!0 $ is true
|

Bitwise "or" operator. Supports more than 2 input values. Several examples:

  • $ 1 | 0 = 1 $
  • $ 1 | 2 | 4 = 7 $
||
Logical "or" operator.
&
Bitwise "and" operator. Supports exactly 2 input values.
&&
Logical "and" operator.
(
Open parenthesis. Used for changing the standard order of operations, where multiplication and division ordinarily take priority over addition and subtraction.
)
Closed parenthesis. Used for changing the standard order of operations, where multiplication and division ordinarily take priority over addition and subtraction.
<
The "less than" comparison operator. When comparing an integer value with its floating-point equivalent, the result is false.
<=
The "less than or equal to" comparison operator. When comparing an integer value with its floating-point equivalent, the result is true.
>
The "greater than" comparison operator. When comparing an integer value with its floating-point equivalent, the result is false.
>=
The "greater than or equal to" comparison operator. When comparing an integer value with its floating-point equivalent, the result is true.
? and :

Provides support for ternary operations. The general format is as follows:

condition ? value_if_true : value_if_false

Supports nested ternary operations using parentheses.

,

Separates values in functions that take more than 1 argument.

"

When placed at the beginning and end of a value, indicates that the Watch Face Format should interpret the value as a string.

==

Compare for equality. When comparing an integer value with its floating-point equivalent, the result is true.

!=

Compare for inequality. When comparing an integer value with its floating-point equivalent, the result is false.