Text type
In Hive, a text (often called “string” in other programming languages) must be surrounded with quotation marks (”). All the operations and functions described on this page work with literal texts, components, and variables alike:
var t = "Hello, ";
t.toUpper() + "world!".toUpper() // returns "HELLO, WORLD!"
Formatted Text
Start and end your text with three quotes (”””) instead of one to create a formatted text. A formatted text can span over multiple lines (preserving each new line), you can use quotation marks without having to escape them and embed code fragments in it:
var answer = 42;
"""The answer is of course "{=answer}".
What else?"""
This will create a multi-line text:
The answer is of course "42".
What else?
If you want to use a quotation mark in a regular text, you must escape it with \. A regular text cannot contain line breaks either, instead requiring you to write \n.
The example above can be written as a regular text like this:
"The answer is of course \"" + answer + "\".\nWhat else?"
Not very convenient. Therefore, when you are dealing with text that contains quotation marks or line breaks, we recommend you use formatted text. However, there is one caveat: an opening curly brace ({) must be written as two curly braces in formatted text:
"""This is a curly {{brace}"""
Plain text
This will create this text: This is a curly {brace}
Operations
| name | example | result | description |
|---|---|---|---|
| add text | "awe" + "some" | "awesome" | combines two texts |
| add number | "high " + 5 | "high 5" | combines a text and a number |
| repeat | "$" * 3 | "$$$" | repeats a text a number of times |
Comparing Text
| name | example | result | description |
|---|---|---|---|
| equal to | "up" = "UP" | false | returns true if two texts are equal, case sensitive |
| equal to | "up" ~= "UP" | true | returns true if two texts are equal, case insensitive |
| not equal to | "up" <> "UP" | true | returns true if two texts are not equal, case sensitive |
There is no case insensitive version of the <> operator, but you can negate the outcome of the ~= operator to achieve the same goal: not("up" ~= "UP") returns false, for example.
Whitespace characters such as spaces, tabs, or line breaks are significant when comparing text. The expression "a " = "a" is false because there is a space in the second text that is not present in the first.
Functions
| name | description |
|---|---|
| length | gets the number of characters in a text |
| contains(text) | returns true if a text contains a specific text |
| toUpper | converts a text to upper case |
| toLower | converts a text to lower case |
| take(amount) | gets a subset of a text that contains a specified number of characters |
| skip(amount) | gets a text with a specified number of characters omitted |
| replace(old, new) | replaces all occurrences of a text with a different text |
| encodeHtml | gets an HTML-encoded copy of a text |
| decodeHtml | decodes an HTML-encoded text |
| encodeUrl | gets an URL-encoded copy of a text |
| decodeUrl | decodes an URL-encoded text |
| encodeJson | gets a JSON-encoded copy of a text |
| toNumber(locale) | converts a text to a Number |
| toColor | converts a text to a Color |
| isBase64 | returns true if it is a valid base64 string |
| isEmail | returns true if it is a valid mail address |
length
Returns the number of characters in a text.
| example | result |
|---|---|
"123".length() | 3 |
"awesome".length() | 7 |
contains(text)
Returns true if a text contains a specific text.
| example | result |
|---|---|
"awesome".contains("some") | true |
toUpper
Returns a copy of the text with all characters converted to upper case.
| example | result |
|---|---|
"Awesome!".toUpper() | "AWESOME!" |
toLower
Returns a copy of the text with all characters converted to lower case.
| example | result |
|---|---|
"Awesome!".toLower() | "awesome!" |
take(amount)
Returns a subset of a text that contains a specified number of characters.
-
If a negative number is used, characters will be taken from the end of the text towards the beginning.
-
If the number is greater than the number of characters in the text, the same text will be returned.
-
If the number is zero, an empty text will be returned.
| example | result |
|---|---|
"awesome".take(3) | "awe" |
"awesome".take(-4) | "some" |
"awesome".take(100) | "awesome" |
"awesome".take(0) | "" |
skip(amount)
Returns a text with a specified number of characters omitted.
-
If a negative number is used, characters will be skipped from the end of the text toward the beginning.
-
If the number is greater than the number of characters in the text, an empty text will be returned.
-
If the number is zero, the same text will be returned.
| example | result |
|---|---|
"awesome".skip(3) | "some" |
"awesome".skip(-4) | "awe" |
"awesome".skip(100) | "" |
"awesome".skip(0) | "awesome" |
This function is the exact opposite of take. You can use either one and accomplish the same goal, but often it is easier to reason about a problem when combining the two.
Example: Imagine you wanted to extract 123 from an inventory number like ST-123-XYZ.
The most straightforward way to accomplish this probably is inventoryNumber.skip(3).take(3).
But you could just as well write inventoryNumber.take(6).take(-3). The choice is yours!
replace(old, new)
Replaces all occurrences of a text with a different text.
-
If the searched text isn't found, the function will return the original text
-
All occurrences of the searched text will be replaced, not just the first one.
| example | result |
|---|---|
"awesome".replace("esome", "ful") | "awful" |
"a;divided;text;".replace(";", " ") | "a divided text " |
encodeHtml
Returns a text with all characters replaced that have special meaning in HTML, so that it can be safely used.
Note: while the text may look strange, your browser will still display it correctly.
| example | result |
|---|---|
"I <3 Hive & HTML".EncodeHtml() | "I <3 Hive & HTML" |
decodeHtml
The opposite of EncodeHtml: converts an HTML-encoded text back to its original form.
| example | result |
|---|---|
"I <3 Hive & HTML".DecodeHtml() | "I <3 Hive & HTML" |
encodeUrl
Similar to EncodeHtml, returns a text with all characters replaced that have special meaning in URLs, so that it can be safely used.
| example | result |
|---|---|
"I <3 Hive & HTML".EncodeUrl() | "I+%3C3+Hive+%26+HTML" |
decodeUrl
The opposite of EncodeUrl: converts an URL-encoded text back to its original form.
| example | result |
|---|---|
"I+%3C3+Hive+%26+HTML".DecodeUrl() | "I <3 Hive & HTML" |
encodeJson
Returns a text with all characters replaced that have special meaning in JSON – or that could pose a security risk via injection attacks. The returned text can be safely embedded in a JSON document.
Note: use this on a text that will be embedded in a JSON text, not on a text that contains JSON content itself!
| example | result |
|---|---|
"Dangerous text: \" \\ + <>".encodeJson() | "Dangerous text: \u0022 \\ \u002B \u003C\u003E" |
"""{ "example": "{= "Dangerous text: \" \\ + <>".encodeJson() }" }""" | "{ "example": "Dangerous text: \u0022 \\ \u002B \u003C\u003E" }" |
toNumber(locale)
Converts a text to a number. If the text cannot be converted, for example because it contains non-numerical characters, Empty will be returned.
You can optionally specify a locale to support different number formats, the default is Locale.en
Always provide a fallback value in case the conversion fails. We made it easy to do so with the or operator.
| example | result |
|---|---|
"13.37".toNumber() | 13.37 |
"13$".toNumber() | Empty |
"13$".toNumber() or 1 | 1 |
"13,37".toNumber(Locale.de) | 13.37 |
toColor
Converts a text in hexadecimal color format to a color. If the color format is invalid, an error will be returned.
| example | result |
|---|---|
"#0000ff".ToColor() | 6-digit format: #RRGGBB |
"#f00".ToColor() | 3-digit format: #RGB |
"#ff00".ToColor() | ! ERROR ! invalid format (4 digits) |
isBase64
Returns true if the given text is a valid base64 string.
| example | result |
|---|---|
"".isBase64() | true |
"=".isBase64() | false |
"a=".isBase64() | false |
"Zm9vYmE=".isBase64() | true |
isEmail
Returns true if the text is a valid mail address.
| example | result |
|---|---|
"john.doe@example.com".isEmail() | true |
"john doe@example.com".isEmail() | false |
"john.doe@example".isEmail() | false |
To be considered valid, a mail address must satisfy the following regular expression:
^[\w-]+(?:[\.+][\w-]+)*@(?:[\w-]+\.)+[a-zA-Z0-9-]{2,}$