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

Type Number.

The number of characters in the String.



Methods
base64Decode()

Returns String.

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

base64Encode()

Returns String.

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

charAt(Number:index=0)

Returns 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.

contains(String:pattern)

Returns 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)

Returns Boolean.

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

escape()

Returns 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()

Returns String.

Returns the first character of the String.

hasHtml()

Returns Boolean.

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

lastChar()

Returns String.

Returns the last character of the String.

newlinesToBr()

Alias of String.nl2br().

nl2br()

Returns String.

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

noHtml(String:exceptions)

Returns 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.

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

Returns String.

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

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.


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!
split(String:separator [, Number:limit])

Returns 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)

Returns Boolean.

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

substring(Number:start [, Number:length])

Returns String.

Returns a segment of a string, at least one character in length, determined by the start and length parameters.

toBoolean()

Returns 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()

Returns String.

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()

Returns 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])

Returns 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()

Returns String.

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

toLowerCase()

Returns String.

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

toNumber()

Returns Number.

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

toUpper()

Returns String.

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

toUpperCase()

Returns String.

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

toUrl()

Returns 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.

trim()

Returns 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.
truncate(Number:length [, String:suffix])

Returns 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()

Returns String.

Alias of String.upperCaseFirst().

ucWords()

Returns String.

Alias of String.upperCaseWords().

upperCaseFirst()

Returns String.

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

upperCaseWords()

Returns String.

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

urlDecode()

Returns String.

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

urlEncode()

Returns String.

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

wrap(String:tag)

Returns 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>
?>