String

Extends Literal. Strings contain characters or numbers and may be any text within single or double quotes. They do differ so it's worth reading further.

Single quoted strings

Strings enveloped within single quotes are taken as literal strings with only two escaped characters: 

  1. To specify a literal single quote, escape it with a backslash (\). 
  2. To specify a literal backslash, double it (\\). 

Any other escape sequences you might be used to, such as \r or \n, will be output literally as part of the string and don't have any special meaning.

// a simple string within single quotes
var myString1 = 'It\'s my Birthday today'; // It's my Birthday today

// strings may have embedded new lines
var myString2 = 'You can also have embedded newlines in 
strings this way as it is
okay to do';
    
var myString3 = 'A \n is just part of a string in single quotes';

Double quoted strings

Strings enveloped within double quotes are not so literal and accept a range of escape sequences.


var myString2 = "text within \n double quotes"; // the \n represents a new line

EV Script accepts the following escape strings within double quoted strings:

\n Newline
\r Carriage return
\t Tab
\" Double quotes
\\ Backslash

Any other character sequence will result in a literal string interpretation.

Properties
length Number

The number of characters in the String (multi-byte character safe).



Methods
base64Decode() String

Returns a new unencoded string leaving the original base64 encoded string unmutated.

base64Encode() String

Returns a new base64 encoded string leaving the original string unmutated.

base64UrlDecode() String

Returns a new unencoded string leaving the original base64 URL encoded string unmutated.

base64UrlEncode() String

Returns a new URL-safe base64 encoded string leaving the original string unmutated.

charAt(Number:index=0) String

Returns a character at the supplied index. If an index is not supplied the first character of the string will be returned. Note that in EVML indexes start from 0. So the first character of a string has an index of 0.

charCodeAt(Number:index=0) String

Returns a character code at the supplied index. If an index is not supplied the character code for the first character of the string will be returned. Note that in EVML indexes start from 0. So the first character of a string has an index of 0.

compare(String:value) Number

Alias of String.localeCompare()

concat(...String:value) string

Combines the text of one or more strings and returns a new string.

contains(String:pattern) Boolean

Determines whether one string may be found within another string. This method accepts a simple string, but also allows a regular expression. Returns true if the pattern exists or false if not. 


var myString = "I am a fish! I am a fish! I am a fish!";
print(myString.contains('fish')); // true
print(myString.contains('Fish')); // false
print(myString.contains('/FISH/i')); // true
print(myString.contains(/FISH/i)); // true
endsWith(String:needle) Boolean

Determines whether a string ends with the character(s) of another string, returning true or false as appropriate.

escape() String

Escape the string into a safer representation of itself by converting special HTML characters into visual representation of the String rather than as code.

  • & (ampersand) becomes &
  • " (double quote) becomes "
  • ' (single quote) becomes '
  • < (less than) becomes &lt;
  • > (greater than) becomes &gt;

This method is important in escaping user input or data within HTML attributes.


<?ev
    var myString = 'A box of 9" nuts & bolts';
?>
<img src="..." alt="{{ myString.escape() }}" />

Renders as:


<img src="..." alt="A box of 9&quot; nuts &amp; bolts" />

firstChar() String

Returns the first character of the String.

hasHtml() Boolean

Determines whether the String contains HTML, returning true or false as appropriate.

includes(String:needle) Boolean

Alias of String.contains()

indexOf(String:needle, Number:fromIndex) Number

Returns the index within the calling String object of the first occurrence of the specified value, starting the search at fromIndex.
Returns -1 if the value is not found.

lastChar() String

Returns the last character of the String.

lastIndexOf(String:needle, Number:fromIndex) Number

Returns the index within the calling String object of the last occurrence of the specified value, searching backwards from fromIndex.
Returns -1 if the value is not found.

localeCompare(String:value) Number

Uses the current locale to perform a unicode compatible comparison of two strings. Returns a number indicating whether a reference string comes before, or after, or is the same as the given string valuein sort order.

  • 1 if the current string is greater than the value supplied.
  • 0 if the current string is equal to the value supplied.
  • -1 if the current string is less than the value supplied

This method is useful for string comparison when sorting arrays.

match() Array | null

Returns an Array containing matches, or null if no matches are found.

Parameters

  • regexp
    A regular expression either supplied as a Regexp object or as a String.
matchAll() Array

Returns an Array of all results matching a string against a regular expression.

Parameters

  • regexp
    A regular expression either supplied as a Regexp object or as a String.
newlinesToBr() String

Alias of String.nl2br().

nl2br() String

Returns a new String converting embedded or escaped newlines (\n within double quoted strings) to an HTML break (<br>) tag.

noHtml(String:exceptions) String

Remove HTML tags from the String returning a new String with the result. You may permit some tags using the exceptions argument to this method. These are supplied as a String of tags e.g. "<p><br>". tag.

padEnd(Number:targetLength, String:padString) String

Pads the current string with a given string (repeated, if needed) so that the resulting string reaches a given length. The padding is applied from the end (right) of the current string.

padStart(Number:targetLength, String:padString) String

Pads the current string with another string (repeated, if needed) so that the resulting string reaches the given length. The padding is applied from the start (left) of the current string.

repeat(Number:count) String

Constructs and returns a new string which contains the specified number of copies of the string on which it was called, concatenated together.

replace(String:pattern, String:replacement [, Number:limit]) String

Search the current string for a pattern and replace them with a replacement and return a new String with the result.

Parameters

  • pattern
    may be a string or a regular expression represented as a String.
  • replacement
    should be a string to replace the pattern with. Your replacement may include a part or all of the original pattern using $n group matches, see example 3 below for...an example in it's simplest form.

  • limit
    The the number of time from the start of the string to execute a successful replacement. By default this is set to -1, which means unlimited.

Examples


var myString = "I really enjoy a good fish dish!";
// example 1
print(myString.replace('fish', 'pasta')); 
// I really enjoy a good pasta dish!

// example 2
print(myString.replace('I', "You'll", 1)); 
// You'll really enjoy a good fish dish!

// example 3
print(myString.replace('/(fish)/i', 'pasta or $1')); 
// I really enjoy a good pasta or fish dish!
search() String

Searches the String for a match based on a regular expression and returns the index of the first match, or -1 if not match was found.

Parameters

  • regexp
    A regular expression either supplied as a Regexp object or as a String.
slice(Number:beginIndex [, Number:endIndex]) String

Extracts a section of a string and returns it as a new string, without modifying the original string.

beginIndex
The zero-based index at which to begin extraction. If negative, it is treated as strLength + (beginIndex) where strLength is the length of the string (for example, if beginIndex is -3 it is treated as strLength - 3). If beginIndex is greater than or equal to the length of the string, slice() returns an empty string.

endIndex
Optional. The zero-based index before which to end extraction. The character at this index will not be included. If endIndex is omitted, slice() extracts to the end of the string. If negative, it is treated as strLength + endIndex where strLength is the length of the string (for example, if endIndex is -3 it is treated as strLength - 3).

split(String:separator [, Number:limit]) Array

Splits a String in to an Array of substrings. The separator may be a String or a Regular Expression. If limit is omitted the split will occur across all matches.

startsWith(String:needle) Boolean

Determines whether a string starts with the character(s) of another string, returning true or false as appropriate.

substring(Number:indexStart [, Number:indexEnd]) String

Extracts characters from indexStart up to but not including indexEnd.

indexStart
An integer between 0 and the length of the string, specifying the offset into the string of the first character to include in the returned substring.

indexEnd
Optional An integer between 0 and the length of the string, which specifies the offset into the string of the first character not to include in the returned substring.

  • If indexStart equals indexEnd, substring() returns an empty string.
  • If indexEnd is omitted, substring() extracts characters to the end of the string.
  • If either argument is less than 0 or is NaN, it is treated as if it were 0.
  • If either argument is greater than length(), it is treated as if it were length().
  • If indexStart is greater than indexEnd, then the effect of substring() is as if the two arguments were swapped; for example, str.substring(1, 0) == str.substring(0, 1).
t(String:reference [, Object:config]) String

Alias of String.translate()

toBoolean() Boolean

Convert the current String to a Boolean and return the result. Strings with no length are result in a false value, whilst strings with length are returned as true.

toColor() Color

Represent the current string as a hexideciaml colour reference in a new String leaving the original unmutated.


<?ev
    var str = "Evance.it";
    print(str.toColor());
    // #4e2e70
?>
toDom() Dom

Convert a String containing valid HTML/XML format to a Dom Object. The toDom() method is a great little tool and can, in some cases, come in handy, because it gives us access to JQuery style Dom methods, but at server-side. For example:


<?ev
    for(var i in page.children){
        var child = page.children[i];
        
        // wrap the child page title with a link 
        // tag and convert to a DOM Object
        var a = child.title.wrap('<a>').toDom();
        
        // add a href attribute to the page URL
        a.attr('href', child.url);
        
        // add a CSS class to the link
        a.addClass('learn-more');
        
        // output the html as a string
        print(a.html());
    }
?>
toIdentifier([ String:whitespace]) String

Convert the string into an identifier. This is generally useful in creating an ID or a URL slug from any String. Whitespace by default is replaced by a dash '-' unless requested otherwise as an argument. Characters that are not alphabetical or numerical are removed.


var str = "A string - containing strange %$%^&* characters!";
var id = str.toIdentifier(); 
// a-string-containing-strange-characters
toLower() String

Alias of String.toLowerCase() - it's just a shorter version.

toLowerCase() String

Returns a new String with all alphabetical letters in lower case.

toNumber() Number

Convert the string into a Number and returns the result. The original String mustcontain a numeric value.

toUpper() String

Alias of String.toUpperCase() - it's shorter because we're lazy.

toUpperCase() String

Returns a new String with all alphabetical letters in upper case.

toUrl() Url

Returns a new Url object based on the original String. This does of course mean that the original string must be either a relative or absolute Url.

translate([String:reference [, Object:config]]) String

Translation support using Language Packs for Themes.

If the internal value of the String contains text in your theme's default language (e.g. 'Hello' in English) you should supply a Translation reference (e.g. 'greeting.welcome') and an optional translation config object if additional variables or pluralization is required.

If the internal value of the string represents a Translation Reference only an optional config for the translation is needed.

trim() String

Returns a new String with any whitespace removed from the beginning or end of the original. The following whitespace characters will be removed:

  • " "   an ordinary space.
  • "\t"   a tab.
  • "\n"   a new line (line feed).
  • "\r"   a carriage return.
  • "\0"   the NUL-byte.
trimEnd() String

Removes whitespace from the end of a string.

trimLeft() String

Alias of trimStart().

trimRight() String

Alias of trimEnd().

trimStart() String

Removes whitespace from the start of a string.

truncate(Number:length [, String:suffix]) String

Return a new String shortened to the number of characters requested by the length argument. If the originating string is longer than length a String returned includes a suffix. The default value for suffix is &hellip; (…).

ucFirst() String

Alias of String.upperCaseFirst().

ucWords() String

Alias of String.upperCaseWords().

upperCaseFirst() String

Returns a new String with the first character capitalized, if it's alphabetic.

upperCaseWords() String

Returns a new String with the first character of each word capitalized, if that character is alphabetic.

urlDecode() String

Returns a new unencoded String leaving the original URL encoded string unmutated.

urlEncode() String

Returns a new URL encoded String leaving the original string unmutated.

wrap(String:tag) String

Wrap the current string with any valid HTML/XML tag and return the result as a new String. The XML/HTML tag may also include valid HTML/XML attributes. All of the following examples are valid:


<?ev
    var title = "Contact Us";
    
    // example 1: simplest form
    print( title.wrap('<em/>' ); 
    // <em>Contact Us</em>
    
    // example 2: open and closing tags are supported
    print( title.wrap('<strong></strong>' ); 
    // <strong>Contact Us</strong>
    
    // example 3: with attributes
    print( title.wrap('<a href="/content"></a>' ); 
    // <a href="/content">Contact Us</a>
?>