String Functions
These functions can be used when working with and manipulating text and string values.
| Function | Description |
|---|---|
string::concat() | Concatenates strings together |
string::contains() | Check whether a string contains another string |
string::endsWith() | Checks whether a string ends with another string |
string::join() | Joins strings together with a delimiter |
string::len() | Returns the length of a string |
string::lowercase() | Converts a string to lowercase |
string::repeat() | Repeats a string a number of times |
string::replace() | Replaces an occurrence of a string with another string |
string::reverse() | Reverses a string |
string::slice() | Extracts and returns a section of a string |
string::slug() | Converts a string into human and URL-friendly string |
string::split() | Divides a string into an ordered list of substrings |
string::startsWith() | Checks whether a string starts with another string |
string::trim() | Removes whitespace from the start and end of a string |
string::uppercase() | Converts a string to uppercase |
string::words() | Splits a string into an array of separate words |
string::html::encode() | Encodes special characters into HTML entities to prevent HTML injection |
string::html::sanitize() | Sanitizes HTML code to prevent the most dangerous subset of HTML injection |
string::is::alphanum() | Checks whether a value has only alphanumeric characters |
string::is::alpha() | Checks whether a value has only alpha characters |
string::is::ascii() | Checks whether a value has only ascii characters |
string::is::datetime() | Checks whether a string representation of a date and time matches a specified format |
string::is::domain() | Checks whether a value is a domain |
string::is::email() | Checks whether a value is an email |
string::is::hexadecimal() | Checks whether a value is hexadecimal |
string::is::ip() | Checks whether a value is an IP address |
string::is::ipv4() | Checks whether a value is an IP v4 address |
string::is::ipv6() | Checks whether a value is an IP v6 address |
string::is::latitude() | Checks whether a value is a latitude value |
string::is::longitude() | Checks whether a value is a longitude value |
string::is::numeric() | Checks whether a value has only numeric characters |
string::is::semver() | Checks whether a value matches a semver version |
string::is::url() | Checks whether a value is a valid URL |
string::is::uuid() | Checks whether a value is a UUID |
string::semver::compare() | Performs a comparison between two semver strings |
string::semver::major() | Extract the major version from a semver string |
string::semver::minor() | Extract the minor version from a semver string |
string::semver::patch() | Extract the patch version from a semver string |
string::semver::inc::major() | Increment the major version of a semver string |
string::semver::inc::minor() | Increment the minor version of a semver string |
string::semver::inc::patch() | Increment the patch version of a semver string |
string::semver::set::major() | Set the major version of a semver string |
string::semver::set::minor() | Set the minor version of a semver string |
string::semver::set::patch() | Set the patch version of a semver string |
string::concat
The string::concat function concatenates strings together.
API DEFINITIONstring::concat(string...) -> string
The following example shows this function, and its output, when used in a RETURN statement:
RETURN string::concat('this', ' ', 'is', ' ', 'a', ' ', 'test');
"this is a test"
string::contains
The string::contains function checks whether a string contains another string.
API DEFINITIONstring::contains(string, string) -> bool
The following example shows this function, and its output, when used in a RETURN statement:
RETURN string::contains('abcdefg', 'cde');
true
string::endsWith
The string::endsWith function checks whether a string ends with another string.
API DEFINITIONstring::endsWith(string, string) -> bool
The following example shows this function, and its output, when used in a RETURN statement:
RETURN string::endsWith('some test', 'test');
true
string::join
The string::join function joins strings together with a delimiter.
API DEFINITIONstring::join(string, string...) -> string
The following example shows this function, and its output, when used in a RETURN statement:
RETURN string::join(', ', 'a', 'list', 'of', 'items');
"a, list, of, items"
string::len
The string::len function returns the length of a given string.
API DEFINITIONstring::len(string) -> number
The following example shows this function, and its output, when used in a RETURN statement:
RETURN string::len('this is a test');
14
string::lowercase
The string::lowercase function converts a string to lowercase.
API DEFINITIONstring::lowercase(string) -> string
The following example shows this function, and its output, when used in a RETURN statement:
RETURN string::lowercase('THIS IS A TEST');
"this is a test"
string::repeat
The string::repeat function repeats a string a number of times.
API DEFINITIONstring::repeat(string, number) -> string
The following example shows this function, and its output, when used in a RETURN statement:
RETURN string::repeat('test', 3);
"testtesttest"
string::replace
The string::replace function replaces an occurrence of a string with another string.
API DEFINITIONstring::replace(string, string, string) -> string
The following example shows this function, and its output, when used in a RETURN statement:
RETURN string::replace('this is a test', 'a test', 'awesome');
"this is awesome"
string::reverse
The string::reverse function reverses a string.
API DEFINITIONstring::reverse(string) -> string
The following example shows this function, and its output, when used in a RETURN statement:
RETURN string::reverse('this is a test');
"tset a si siht"
string::slice
The string::slice function extracts and returns a section of a string.
API DEFINITIONstring::slice(string, number, number) -> string
The following example shows this function, and its output, when used in a RETURN statement:
RETURN string::slice('this is a test', 10, 4);
"test"
string::slug
The string::slug function converts a string into a human and URL-friendly string.
API DEFINITIONstring::slug(string) -> string
The following example shows this function, and its output, when used in a RETURN statement:
RETURN string::slug('SurrealDB has launched #database #awesome');
"surrealdb-has-launched-database-awesome"
string::split
The string::split function splits a string by a given delimiter.
API DEFINITIONstring::split(string, string) -> array
The following example shows this function, and its output, when used in a RETURN statement:
RETURN string::split('this, is, a, list', ', ');
["this", "is", "a", "list"]
string::startsWith
The string::startsWith function checks whether a string starts with another string.
API DEFINITIONstring::startsWith(string, string) -> bool
The following example shows this function, and its output, when used in a RETURN statement:
RETURN string::startsWith('some test', 'some');
true
string::trim
The string::trim function removes whitespace from the start and end of a string.
API DEFINITIONstring::trim(string) -> string
The following example shows this function, and its output, when used in a RETURN statement:
RETURN string::trim(' this is a test ');
"this is a test"
string::uppercase
The string::uppercase function converts a string to uppercase.
API DEFINITIONstring::uppercase(string) -> string
The following example shows this function, and its output, when used in a RETURN statement:
RETURN string::uppercase('this is a test');
"THIS IS A TEST"
string::words
The string::words function splits a string into an array of separate words.
API DEFINITIONstring::words(string) -> array
The following example shows this function, and its output, when used in a RETURN statement:
RETURN string::words('this is a test');
["this", "is", "a", "test"]
string::html::encode
The string::html::encode function encodes special characters into HTML entities to prevent HTML injection. It is recommended to use this function in most cases when retrieving any untrusted content that may be rendered inside of an HTML document. You can learn more about its behavior from the original implementation.
API DEFINITIONstring::html::encode(string) -> string
The following example shows this function, and its output, when used in a RETURN statement:
RETURN string::html::encode("<h1>Safe Title</h1><script>alert('XSS')</script><p>Safe paragraph. Not safe <span onload='logout()'>event</span>.</p>");
['<h1>Safe Title</h1><script>alert('XSS')</script><p>Safe paragraph. Not safe <span onload='logout()'>event</span>.</p>']
string::html::sanitize
The string::html::sanitize function sanitizes HTML code to prevent the most dangerous subset of HTML injection that can lead to attacks like cross-site scripting, layout breaking or clickjacking. This function will keep any other HTML syntax intact in order to support user-generated content that needs to contain HTML styling. It is only recommended to rely on this function if you want to allow the creators of the content to have some control over its HTML styling. You can learn more about its behavior from the original implementation.
API DEFINITIONstring::html::sanitize(string) -> string
The following example shows this function, and its output, when used in a RETURN statement:
RETURN string::html::sanitize("<h1>Safe Title</h1><script>alert('XSS')</script><p>Safe paragraph. Not safe <span onload='logout()'>event</span>.</p>");
['<h1>Safe Title</h1><p>Safe paragraph. Not safe <span>event</span>.</p>']
string::is::alphanum
The string::is::alphanum function checks whether a value has only alphanumeric characters.
API DEFINITIONstring::is::alphanum(string) -> bool
The following example shows this function, and its output, when used in a RETURN statement:
RETURN string::is::alphanum("ABC123");
true
string::is::alpha
The string::is::alpha function checks whether a value has only alpha characters.
API DEFINITIONstring::is::alpha(string) -> bool
The following example shows this function, and its output, when used in a RETURN statement:
RETURN string::is::alpha("ABCDEF");
true
string::is::ascii
The string::is::ascii function checks whether a value has only ascii characters.
API DEFINITIONstring::is::ascii(string) -> bool
The following example shows this function, and its output, when used in a RETURN statement:
RETURN string::is::ascii("ABC123");
true
string::is::datetime
The string::is::datetime function checks whether a string representation of a date and time matches a specified format.
API DEFINITIONstring::is::datetime(string, string) -> bool
The following example shows this function, and its output, when used in a RETURN statement:
RETURN string::is::datetime("2015-09-05 23:56:04", "%Y-%m-%d %H:%M:%S");
Responsetrue
This can be useful when validating datetimes obtained from other sources that do not use the ISO 8601 format.
RETURN string::is::datetime("5sep2024pm012345.6789", "%d%b%Y%p%I%M%S%.f");
Responsetrue
RETURN string::is::datetime("23:56:00 2015-09-05", "%Y-%m-%d %H:%M");
Responsefalse
string::is::domain
The string::is::domain function checks whether a value is a domain.
API DEFINITIONstring::is::domain(string) -> bool
The following example shows this function, and its output, when used in a RETURN statement:
RETURN string::is::domain("surrealdb.com");
true
string::is::email
The string::is::email function checks whether a value is an email.
API DEFINITIONstring::is::email(string) -> bool
The following example shows this function, and its output, when used in a RETURN statement:
RETURN string::is::email("info@surrealdb.com");
true
string::is::hexadecimal
The string::is::hexadecimal function checks whether a value is hexadecimal.
API DEFINITIONstring::is::hexadecimal(string) -> bool
The following example shows this function, and its output, when used in a RETURN statement:
RETURN string::is::hexadecimal("ff009e");
true
string::is::ip
The string::is::ip function checks whether a value is an IP address.
API DEFINITIONstring::is::ip(string) -> bool
The following example shows this function, and its output, when used in a RETURN statement:
RETURN string::is::ip("192.168.0.1");
true
string::is::ipv4
The string::is::ipv4 function checks whether a value is an IP v4 address.
API DEFINITIONstring::is::ipv4(string) -> bool
The following example shows this function, and its output, when used in a RETURN statement:
RETURN string::is::ipv4("192.168.0.1");
true
string::is::ipv6
The string::is::ipv6 function checks whether a value is an IP v6 address.
API DEFINITIONstring::is::ipv6(string) -> bool
The following example shows this function, and its output, when used in a RETURN statement:
RETURN string::is::ipv6("2001:0db8:85a3:0000:0000:8a2e:0370:7334");
true
string::is::latitude
The string::is::latitude function checks whether a value is a latitude value.
API DEFINITIONstring::is::latitude(string) -> bool
The following example shows this function, and its output, when used in a RETURN statement:
RETURN string::is::latitude("-0.118092");
true
string::is::longitude
The string::is::longitude function checks whether a value is a longitude value.
API DEFINITIONstring::is::longitude(string) -> bool
The following example shows this function, and its output, when used in a RETURN statement:
RETURN string::is::longitude("51.509865");
true
string::is::numeric
The string::is::numericfunction checks whether a value has only numeric characters.
API DEFINITIONstring::is::numeric(string) -> bool
The following example shows this function, and its output, when used in a RETURN statement:
RETURN string::is::numeric("1484091748");
true
string::is::semver
The string::is::semver function checks whether a value matches a semver version.
API DEFINITIONstring::is::semver(string) -> bool
The following example shows this function, and its output, when used in a RETURN statement:
RETURN string::is::semver("1.0.0");
true
string::is::url
The string::is::url function checks whether a value is a valid URL.
API DEFINITIONstring::is::url(string) -> bool
The following example shows this function, and its output, when used in a RETURN statement:
RETURN string::is::url("https://surrealdb.com");
true
string::is::uuid
The string::is::uuid function checks whether a value is a UUID.
API DEFINITIONstring::is::uuid(any) -> bool
The following example shows this function, and its output, when used in a RETURN statement:
RETURN string::is::uuid("018a6680-bef9-701b-9025-e1754f296a0f");
true
string::semver::compare Since 1.2.0
The string::semver::compare function performs a comparison on two semver strings and returns a number.
A value of -1 indicates the first version is lower than the second, 0 indicates both versions are
equal, and 1 indicates the first version is higher than the second.
API DEFINITIONstring::semver::compare(string, string) -> number
The following example shows this function, and its output, when used in a RETURN statement:
RETURN string::semver::compare("1.0.0", "1.3.5");
-1
string::semver::major Since 1.2.0
The string::semver::major function extracts the major number out of a semver string.
API DEFINITIONstring::semver::major(string) -> number
The following example shows this function, and its output, when used in a RETURN statement:
RETURN string::semver::major("3.2.6");
3
string::semver::minor Since 1.2.0
The string::semver::minor function extracts the minor number out of a semver string.
API DEFINITIONstring::semver::minor(string) -> number
The following example shows this function, and its output, when used in a RETURN statement:
RETURN string::semver::minor("3.2.6");
2
string::semver::patch Since 1.2.0
The string::semver::patch function extracts the patch number out of a semver string.
API DEFINITIONstring::semver::patch(string) -> number
The following example shows this function, and its output, when used in a RETURN statement:
RETURN string::semver::patch("3.2.6");
6
string::semver::inc::major Since 1.2.0
The string::semver::inc::major function increments the major number of a semver string. As a result, the minor and patch numbers are reset to zero.
API DEFINITIONstring::semver::inc::major(string) -> string
The following example shows this function, and its output, when used in a RETURN statement:
RETURN string::semver::inc::major("1.2.3");
"2.0.0"
string::semver::inc::minor Since 1.2.0
The string::semver::inc::minor function increments the minor number of a semver string. As a result, the patch number is reset to zero.
API DEFINITIONstring::semver::inc::minor(string) -> string
The following example shows this function, and its output, when used in a RETURN statement:
RETURN string::semver::inc::minor("1.2.3");
"1.3.0"
string::semver::inc::patch Since 1.2.0
The string::semver::inc::patch function increments the patch number of a semver string.
API DEFINITIONstring::semver::inc::patch(string) -> string
The following example shows this function, and its output, when used in a RETURN statement:
RETURN string::semver::inc::patch("1.2.3");
"1.2.4"
string::semver::set::major Since 1.2.0
The string::semver::set::major function sets the major number of a semver string without changing the minor and patch numbers.
API DEFINITIONstring::semver::set::major(string, number) -> string
The following example shows this function, and its output, when used in a RETURN statement:
RETURN string::semver::set::major("1.2.3", 9);
"9.2.3"
string::semver::set::minor Since 1.2.0
The string::semver::set::minor function sets the minor number of a semver string without changing the major and patch numbers.
API DEFINITIONstring::semver::set::minor(string, number) -> string
The following example shows this function, and its output, when used in a RETURN statement:
RETURN string::semver::set::minor("1.2.3", 9);
"1.9.3"
string::semver::set::patch Since 1.2.0
The string::semver::set::patch function sets the patch number of a semver string without changing the major and minor numbers.
API DEFINITIONstring::semver::set::patch(string, number) -> string
The following example shows this function, and its output, when used in a RETURN statement:
RETURN string::semver::set::patch("1.2.3", 9);
"1.2.9"