Functions
Functions are like ready-made tools that perform specific tasks. They take in data as input, process it, and return a result.
Here are a few examples of what functions can do:
- Count the number of characters in a text.
- Search for a specific word in a text.
- Determine the smallest number between two numbers.
Functions in ProtoPie have a specific structure:
function(argument: TYPE)
→ result: TYPEfunction(argument1: TYPE, argument2: TYPE)
→ result: TYPEfunction(argument1: TYPE, argument2: TYPE, argument3: TYPE)
→ result: TYPE
Functions usually use one or multiple arguments (data) as input—the values a function uses to perform a task. Arguments, as well as the result, are values that are always of a specific type. A type could be a text, number, or color.
There are various categories to choose from:
Text
concat(source1: TEXT, source2: TEXT)
TEXTCombine two separate texts into one.
Example:concat("hello", "world")"helloworld"
indexOf(source: TEXT, searchValue: TEXT)
NUMBERFind the starting position of a keyword in a text. If the keyword isn't present in the text, the returned value is -1.
Example:indexOf("hello world", "world")6
Example:indexOf("hello world", "hello")0
Example:indexOf("hello world", "goodbye")-1
- Use indexOf for use cases like email validation. See use case example.
length(source: TEXT)
NUMBERCount the number of characters in a text.
Example:length("hello")5
Example:length("helloworld")10
Example:length("hello world")11
- Use length for use cases like password validation. See use case example.
lowerCase(source: TEXT)
TEXTConvert any text from uppercase to lowercase
Example:lowerCase("Hello")"hello"
upperCase(source: TEXT)
TEXTConvert any text from lowercase to UPPERCASE.
Example:upperCase("Hello")"HELLO"
left(source: TEXT, count: NUMBER)
TEXTExtract a part of a text from the left side based on a specific number of characters.
Example:left("hello", 3)"hel"
right(source: TEXT, count: NUMBER)
TEXTExtract a part of a text from the right side based on a specific number of characters.
Example:right("hello", 2)"lo"
lpad(source: TEXT, length: NUMBER, pad: TEXT)
TEXTLeft-pad a text with another text, to a specific length.
Example:lpad("5", 2, "0")"05"
Example:lpad("5", 4, "0")"0005"
rpad(source: TEXT, length: NUMBER, pad: TEXT)
TEXTRight-pad a text with another text, to a specific length.
Example:rpad("5", 2, "1")"51"
Example:rpad("5", 6, "1")"511111"
repeat(source: TEXT, count: NUMBER)
TEXTRepeat a text a specific number of times.
Example:repeat("hello", 2)"hellohello"
Example:repeat("hello", 3)"hellohellohello"
replace(source: TEXT, from: TEXT, to: TEXT)
TEXTReplace a part of a text with another text.
Example:replace("helloworld", "world", "protopie")"helloprotopie"
Example:replace("goodbye, John", "goodbye", "thank you")"thank you, John"
trim(source: TEXT)
TEXTRemove whitespaces on both sides of a text.
Example:trim(" helloworld ")"helloworld"
Example:trim(" helloworld ")"helloworld"
ltrim(source: TEXT)
TEXTRemove whitespace from the left side of a text.
Example:ltrim(" helloworld ")"helloworld "
rtrim(source: TEXT)
TEXTRemove whitespace from the right side of a text.
Example:rtrim(" helloworld ")" helloworld"
regexextract(source: TEXT, regular expression: TEXT)
TEXTExtracts the first substrings of a text that match the provided regular expression.
Example:regexextract("Google Doc 101", "[0-9]+")"101"
Example:regexextract("The price today is $826.25", "[0-9]*\.[0-9]+[0-9]+")"826.25"
regexreplace(source: TEXT, regular expression: TEXT, replacement: TEXT)
TEXTReplaces part of a text string with a different text string using regular expressions.
Example:regexreplace("Google Doc 101", "[0-9]+", "777")"Google Doc 777"
Example:regexreplace("The price today is $826.25", "[0-9]*\.[0-9]+[0-9]+", "315.75")"The price is $315.75"
parseJson(source: TEXT, key: TEXT)
TEXTParses a valid JSON string and returns the corresponding value.
Example:parseJson("{\"name\":\"John\", \"age\":30, \"car\":null}", "age")"30"
Example:parseJson("{\"name\":\"John\", \"age\":30, \"car\":null}", "name")"John"
- send JSON string to pies via Bridge apps in ProtoPie Connect (e.g., message: “AutomobileSignal”, value: “json string”).
- store a value inside a Pie variable via the Receive trigger.
- use the data values inside the JSON string.
For example, let's consider parseJson(var, "key"). Here, var is the text variable that stores the JSON string, and "key" is the key to parse. The latter supports nested key calling and simple references to array-like objects via the . (dot) notation.
The parseJson function greatly simplifies working with complex data structures in ProtoPie. Additionally, since most API responses are in JSON format, being able to use parseJson within Pies makes working with APIs much more straightforward.
You can use the parseJson function to:
To learn more, take a look at this Pie example.
Math
pow(source: NUMBER, exponent: NUMBER)
NUMBERCalculate the result of the first number raised to the power of the second number.
Example:pow(2, 3)8
sqrt(source: NUMBER)
NUMBERCalculate the square root of a number. This doesn't work for negative numbers.
Example:sqrt(9)3
Example:sqrt(2)1.41
min(source1: NUMBER, source2: NUMBER)
NUMBERExtract the smallest of two numbers.
Example:min(0, 1)0
max(source1: NUMBER, source2: NUMBER)
NUMBERExtract the largest of two numbers.
Example:max(0, 1)1
abs(value: NUMBER)
NUMBERReturn the absolute value of a number. In practice, this comes down to removing the negative sign in front of a number.
Example:abs(-1)1
Example:abs(5 - 25)20
sign(value: NUMBER)
NUMBERCheck if a number is positive or negative. Return 1 if a number is positive. Return -1 if a number is negative. Return 0 if a number is 0.
Example:sign(5)1
Example:sign(-10)-1
Example:sign(0)0
round(source: NUMBER)
NUMBERReturn the rounded value of a number.
Example:round(3.49)3
Example:round(1.5)2
Example:round(6.79)7
floor(source: NUMBER)
NUMBERReturn the nearest whole number down.
Example:floor(1.5)1
Example:floor(2.99)2
ceil(source: NUMBER)
NUMBERReturn the nearest whole number up.
Example:ceil(1.5)2
Example:ceil(4.3)5
random()
NUMBERa random decimal number between 0 and 1
Example:random()a random decimal number between 0 and 1
random(min: NUMBER, max: NUMBER)
NUMBERReturn a decimal number randomly between two given numbers.
Example:random(1, 5)a random decimal number between 1 and 5
randomInt(min: NUMBER, max: NUMBER)
NUMBERReturn a whole number randomly between two given numbers.
Example:randomInt(1, 5)a random whole number between 1 and 5
radians(degrees: NUMBER)
NUMBERConvert degrees to radians.
Example:radians(180)3.14 = π
Example:radians(90)1.57 = π / 2
degrees(radians: NUMBER)
NUMBERConvert radians to degrees.
Example:degrees($pi)180
Example:degrees($pi / 2)90
sin(radian: NUMBER)
NUMBERCalculate the sine of a number in radians.
Example:sin($pi / 2)1
Example:sin($pi / 6)0.5
cos(radian: NUMBER)
NUMBERCalculate the cosine of a number in radians.
Example:cos(0)1
Example:cos($pi / 2)0
tan(radian: NUMBER)
NUMBERCalculate the tangent of a number in radians.
Example:tan($pi / 4)1
Example:tan(0)0
asin(x: NUMBER)
NUMBERCalculate the arcsine (in radians) of x.
Example:asin(1)1.57 = π / 2
Example:asin(0.5)0.52 = π / 6
acos(x: NUMBER)
NUMBERCalculate the arccosine (in radians) of x.
Example:acos(1)0
Example:acos(0)1.57 = π / 2
atan(x: NUMBER)
NUMBERCalculate the arctangent (in radians) of x.
Example:atan(1)0.79 = π / 4
Example:atan(0)0
atan2(y: NUMBER, x: NUMBER)
NUMBERCalculate the arctangent (in radians) of x and y, also known as the angle in the Euclidean plane.
Example:atan2(1, 0)1.57 = π / 2
Example:atan2(1, 1)0.79 = π / 4
Color
color(red: NUMBER, green: NUMBER, blue: NUMBER)
COLORReturn a color value (hex color code) based on an RGB value.
Example:color(255, 255, 255)#FFFFFF
Example:color(255, 102, 97)#FF6661
red(source: COLOR)
NUMBERReturn the red RGB parameter of a hex color code.
Example:red(#FF0000)255
Example:red(#008000)0
Example:red(#0000FF)0
green(source: COLOR)
NUMBERReturn the green RGB parameter of a hex color code.
Example:green(#FF0000)0
Example:green(#008000)128
Example:green(#0000FF)0
blue(source: COLOR)
NUMBERReturn the blue RGB parameter of a hex color code.
Example:blue(#FF0000)0
Example:blue(#008000)0
Example:blue(#0000FF)255
Type Conversion
number(source: TEXT)
NUMBERConvert a text to a number. This doesn't work if the text cannot be converted to a number.
Example:number("1234")1234
Example:number("94.27")94.27
text(source: NUMBER)
TEXTConvert a number to a text.
Example:text(1234)"1234"
Example:text(94.27)"94.27"
Example:text(1 + 3)"4"
format(source: NUMBER, format: TEXT)
TEXTConvert a number to a text with a certain format. # is a placeholder for whole numbers whereas 0 represents the fractional part.
Example:format(1234.567, "#")"1235"
Example:format(1234.567, "#,###")"1,235"
Example:format(1234.567, "#.###,00")"1.234,57"
Example:format(1234.567, "#,##.00")"12,34.57"
Example:format(1234.567, "#,###.00")"1,234.57"
color(source: TEXT)
COLORConvert a text to a color value (hex color code). This doesn't work if the text doesn't have a hex color code structure.
Example:color("#FFFFFF")#FFFFFF
Layers
layer(source: TEXT)
LAYERRefer to a layer.
- Use this as part of a formula or a different function.
layer(source: TEXT).property
TEXT or NUMBERRefer to a layer's property. Learn more about layer properties.
Example:layer("Rectangle 1").xx-coordinate of the layer called Rectangle 1
Example:layer("Oval 1").opacityOpacity of the layer called Oval 1
Example:layer("Input 1").textText in the input layer called Input 1
parent(layerName: LAYER)
LAYERRefer to the parent layer, e.g., a container or component.
- Use this as part of a formula or a different function.
parent(layerName: LAYER).property
TEXT or NUMBERRefer to the parent layer's property. Learn more about layer properties.
Example:parent(`Rectangle 1`).xx-coordinate of Rectangle 1 its parent layer
Example:parent(`Oval 1`).opacityOpacity of Oval 1 its parent layer
initial(layerName: LAYER, layerProperty: TEXT)
TEXT or NUMBERReturn the initial value (before any interactions) of a specific layer property. Learn more about layer properties.
Example:initial(`Rectangle 1`, "x")Initial x-coordinate of Rectangle 1
Example:initial(`Oval 1`, "opacity")Initial opacity of Oval 1
Example:initial(`Input 1`, "text")Initial text in Input 1
Relative Coordinates
toLayerX(containerName: LAYER, x: NUMBER, y: NUMBER)
NUMBERConvert a x coordinate relative to the screen into the corresponding x coordinate relative to a container or component. The coordinates of layers inside a container or component are by default relative to the container or component they are in.
- For example, if you want to get the x coordinate relative to a container `Container 1` based on the position (100, 200) relative to the screen, use the following function:
toLayerX(`Container 1`, 100, 200)returns the x coordinate relative to `Container 1` based on the x coordinate `100` relative to the screen.
toLayerY(containerName: LAYER, x: NUMBER, y: NUMBER)
NUMBERConvert a y coordinate relative to the screen into the corresponding y coordinate relative to a container or component. The coordinates of layers inside a container or component are by default relative to the container or component they are in.
- For example, if you want to get the y coordinate relative to a container `Container 1` based on the position (100, 200) relative to the screen, use the following function:
toLayerY(`Container 1`, 100, 200)returns the y coordinate relative to `Container 1` based on the y coordinate `200` relative to the screen.
toScreenX(containerName: LAYER, x: NUMBER, y: NUMBER)
NUMBERConvert a x coordinate relative to a container or component into the corresponding x coordinate relative to the screen. The coordinates of layers inside a container or component are by default relative to the container or component they are in.
- For example, if you want to get the x coordinate relative to the screen based on the position (10, 20) relative to a container `Container 1` , use the following function:
toScreenX(`Container 1`, 10, 20)returns the x coordinate relative to the screen based on the x coordinate `10` relative to `Container 1`.
toScreenY(containerName: LAYER, x: NUMBER, y: NUMBER)
NUMBERConvert a y coordinate relative to a container or component into the corresponding y coordinate relative to the screen. The coordinates of layers inside a container or component are by default relative to the container or component they are in.
- For example, if you want to get the y coordinate relative to the screen based on the position (10, 20) relative to a container `Container 1`, use the following function:
toScreenY(`Container 1`, 10, 20)returns the y coordinate relative to the screen based on the y coordinate `20` relative to `Container 1`.
Time & Date
Note: the time & date functions follow the ISO8601 format.
timeNow()
TEXTRetrieves the current time information.
Example:timeNow()17:44:50.123
time(hour: NUMBER, min: NUMBER, sec: NUMBER)
TEXTConstructs a time object with the provided hour, minute, and second values, presenting the time in the standard "hour:minute:second" format.
Example:time(14, 50, 23)14:50:23
hour()
NUMBERRetrieves and returns the hour component of a given time in a 24-hour format. This function takes a time value as input and extracts the hour part, providing it as a numerical value.
Example:hour("17:44:30")17
minute()
NUMBERExtracts and returns the minute component of a given time in a 24-hour format. This function takes a time value as input and retrieves the minute part, providing it as a numerical value.
Example:minute("17:44:30")44
second()
NUMBERRetrieves and returns the second component of a given time in a 24-hour format. This function takes a time value as input and extracts the second part, providing it as a numerical value.
Example:second("17:44:30")30
diffTime()
NUMBERCalculates the difference between two points in time, typically represented as hours, minutes, and seconds. This function takes two time values as input and calculates the time duration or time interval between them, providing the result in hours, minutes, and/or seconds.
Example:diffTime("17:45:30", "18:45:30", "H")1
Example:diffTime("17:45:30", "18:45:30", "M")60
Example:diffTime("17:45:30", "18:45:30", "S")3600
formatTime()
TEXTTransforms a time value into a human-readable string representation, following a specified format pattern. This function accepts a time value as input and returns a formatted string that conforms to the provided format pattern.
Example:formatTime("11:44:30", "HHa")11am
Example:formatTime("11:44:30", "HHam mm")11am 44
Example:formatTime("11:44:30", "hh:mm a")11:40 am
dateNow()
TEXTRetrieves and returns the current date at the moment of execution.
Example:dateNow()2023-09-22
date(year: NUMBER, month: NUMBER, day: NUMBER)
TEXTIs employed to construct a date object with the provided year, month, and day values, yielding the date in the standard "year-month-day" format.
Example:date(2014, 12, 8)2014-12-08
year()
NUMBERExtracts and returns the year component from a date string in the "year-month-day" format. This function takes a date value as input and retrieves the year part as a numerical value.
Example:year("2014-12-8")2014
month()
NUMBERExtracts and returns the month component from a date string in the "year-month-day" format. This function takes a date value as input and retrieves the month part as a numerical value.
Example:month("2014-12-8")12
day()
NUMBERExtracts and returns the day component from a date string in the "year-month-day" format. This function takes a date value as input and retrieves the day part as a numerical value.
Example:day("2014-12-8")8
diffDate()
NUMBERThis function calculates the difference between two dates and returns it as a numerical value based on a specified time unit ("Y" for years, "M" for months, or "D" for days). The functions also include "YD" for years and days, "YM" for years and months, and "MD" for months and days, providing more granular differences between two dates by focusing on specific components within the span of the overall result. Note: When using the diffDate("from", "to", "format") function, if the "to" date is earlier than the "from" date, it will output -1.
Example:diffDate("1973-02-24", "1969-05-16", "Y")-1
Example:diffDate("1973-02-24", "1969-05-16", "M")-1
Example:diffDate("1973-02-24", "1969-05-16", "D")-1
Example:diffDate("1969-05-16", "1973-02-24", "Y")3
Example:diffDate("1969-05-16", "1973-02-24", "M")45
Example:diffDate("1969-05-16", "1973-02-24", "D")1380
Example:diffDate("1969-05-16", "1973-02-24", "MD")8
Example:diffDate("2023-01-01", "2023-02-10", "MD")9
Example:diffDate("1969-05-16", "1973-02-24", "YM")9
Example:diffDate("1969-05-16", "1973-02-24", "YD")284
Example:diffDate("2023-01-01", "2023-02-10", "YD")40
formatDate()
TEXTTakes a date value and a format string as input and returns a formatted date string according to the provided pattern.
Example:formatDate("2023-06-01", "DD/MM/YYYY")01/06/2023
Example:formatDate("2023-06-01", "YYYY MMMM dddd")2023 June Thursday
Example:formatDate("2023-06-01", "MMM DD, YY")Jun 01, 23
epochtodate(timestamp: NUMBER)
TEXTIs used to convert a Unix epoch timestamp in milliseconds to a DateTime representation in UTC (Universal Time Coordinated). The function is invoked with the format $epochToDate(timestamp: NUMBER), where timestamp represents a Unix epoch timestamp in milliseconds.
Example:epochtodate(0)1970-01-01T00:00:00Z
Example:epochtodate(-1)1969-12-31T23:59:59.999Z
Example:epochtodate(1)1970-01-01T00:00:00.001Z
Example:epochtodate(1655908429662)2022-06-22T14:33:49.662Z
epochtodate(timestamp: NUMBER, format: TEXT)
TEXTEnables the formatting of Unix timestamps into human-readable date and time representations. It accepts a Unix timestamp in milliseconds as the timestamp parameter and an optional format parameter to specify the desired output format.
Example:epochtodate(1695316200000)2023-09-21T17:10:00Z
Example:epochtodate(1695316200000, "hh:mm")17:10
Learn More in ProtoPie School's Masterclass
Looking to learn more about using functions in ProtoPie? Join ProtoPie’s Masterclass for detailed examples and guidance on using some of the functions listed in this documentation.