<html>
<head>
<base href="https://docs.jboss.org/author">
<link rel="stylesheet" href="/author/s/en/2172/19/5/_/styles/combined.css?spaceKey=TEIID&forWysiwyg=true" type="text/css">
</head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
<h2><a href="https://docs.jboss.org/author/display/TEIID/String+Functions">String Functions</a></h2>
<h4>Page <b>edited</b> by <a href="https://docs.jboss.org/author/display/~shawkins">Steven Hawkins</a>
</h4>
<br/>
<h4>Changes (1)</h4>
<div id="page-diffs">
<table class="diff" cellpadding="0" cellspacing="0">
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >|CONCAT\(x, y)|Concatenates x and y with ANSI semantics. If x and/or y is null, returns null.|x, y in \{string}| <br>|CONCAT2\(x, y)|Concatenates x and y with non\-ANSI null semantics. If x and y is null, returns null. If only x or y is null, returns the other value.|x, y in \{string}| <br></td></tr>
<tr><td class="diff-changed-lines" >|ENDSWITH\(x, y)|Checks if <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">x</span> <span class="diff-added-words"style="background-color: #dfd;">y</span> ends with <span class="diff-changed-words"><span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">y</span><span class="diff-added-chars"style="background-color: #dfd;">x</span>.</span> If x or y is null, returns null.|x, y in \{string}, returns boolean| <br></td></tr>
<tr><td class="diff-unchanged" >|INITCAP\(x)|Make first letter of each word in string x capital and all others lowercase|x in \{string}| <br>|INSERT\(str1, start, length, str2)|Insert string2 into string1|str1 in \{string}, start in \{integer}, length in \{integer}, str2 in \{string}| <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
</table>
</div> <h4>Full Content</h4>
<div class="notificationGreySide">
<p>String functions generally take strings as inputs and return strings as outputs. </p>
<p>Unless specified, all of the arguments and return types in the following table are strings and all indexes are 1-based. The 0 index is considered to be before the start of the string.</p>
<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'>Function</th>
<th class='confluenceTh'>Definition</th>
<th class='confluenceTh'>Datatype Constraint</th>
</tr>
<tr>
<td class='confluenceTd'>x || y</td>
<td class='confluenceTd'>Concatenation operator</td>
<td class='confluenceTd'>x,y in {string}, return type is string</td>
</tr>
<tr>
<td class='confluenceTd'>ASCII(x)</td>
<td class='confluenceTd'>Provide ASCII value of the left most character in x. The empty string will as input will return null. </td>
<td class='confluenceTd'>return type is integer</td>
</tr>
<tr>
<td class='confluenceTd'>CHR(x) CHAR(x)</td>
<td class='confluenceTd'>Provide the character for ASCII value x [a]</td>
<td class='confluenceTd'>x in {integer}</td>
</tr>
<tr>
<td class='confluenceTd'>CONCAT(x, y)</td>
<td class='confluenceTd'>Concatenates x and y with ANSI semantics. If x and/or y is null, returns null.</td>
<td class='confluenceTd'>x, y in {string}</td>
</tr>
<tr>
<td class='confluenceTd'>CONCAT2(x, y)</td>
<td class='confluenceTd'>Concatenates x and y with non-ANSI null semantics. If x and y is null, returns null. If only x or y is null, returns the other value.</td>
<td class='confluenceTd'>x, y in {string}</td>
</tr>
<tr>
<td class='confluenceTd'>ENDSWITH(x, y)</td>
<td class='confluenceTd'>Checks if y ends with x. If x or y is null, returns null.</td>
<td class='confluenceTd'>x, y in {string}, returns boolean</td>
</tr>
<tr>
<td class='confluenceTd'>INITCAP(x)</td>
<td class='confluenceTd'>Make first letter of each word in string x capital and all others lowercase</td>
<td class='confluenceTd'>x in {string}</td>
</tr>
<tr>
<td class='confluenceTd'>INSERT(str1, start, length, str2)</td>
<td class='confluenceTd'>Insert string2 into string1</td>
<td class='confluenceTd'>str1 in {string}, start in {integer}, length in {integer}, str2 in {string}</td>
</tr>
<tr>
<td class='confluenceTd'>LCASE(x)</td>
<td class='confluenceTd'>Lowercase of x</td>
<td class='confluenceTd'>x in {string}</td>
</tr>
<tr>
<td class='confluenceTd'>LEFT(x, y)</td>
<td class='confluenceTd'>Get left y characters of x</td>
<td class='confluenceTd'>x in {string}, y in {integer}, return string</td>
</tr>
<tr>
<td class='confluenceTd'>LENGTH(x)</td>
<td class='confluenceTd'>Length of x</td>
<td class='confluenceTd'>return type is integer</td>
</tr>
<tr>
<td class='confluenceTd'>LOCATE(x, y)</td>
<td class='confluenceTd'>Find position of x in y starting at beginning of y</td>
<td class='confluenceTd'>x in {string}, y in {string}, return integer</td>
</tr>
<tr>
<td class='confluenceTd'>LOCATE(x, y, z)</td>
<td class='confluenceTd'>Find position of x in y starting at z</td>
<td class='confluenceTd'>x in {string}, y in {string}, z in {integer}, return integer</td>
</tr>
<tr>
<td class='confluenceTd'>LPAD(x, y)</td>
<td class='confluenceTd'>Pad input string x with spaces on the left to the length of y</td>
<td class='confluenceTd'>x in {string}, y in {integer}, return string</td>
</tr>
<tr>
<td class='confluenceTd'>LPAD(x, y, z)</td>
<td class='confluenceTd'>Pad input string x on the left to the length of y using character z</td>
<td class='confluenceTd'>x in {string}, y in {string}, z in {character}, return string</td>
</tr>
<tr>
<td class='confluenceTd'>LTRIM(x)</td>
<td class='confluenceTd'>Left trim x of blank chars</td>
<td class='confluenceTd'>x in {string}, return string</td>
</tr>
<tr>
<td class='confluenceTd'>QUERYSTRING(path [, expr [AS name] ...])</td>
<td class='confluenceTd'>Returns a properly encoded query string appended to the given path. Null valued expressions are omitted, and a null path is treated as ''. Names are optional for column reference expressions.e.g. <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false" style="font-size:12px; font-family: ConfluenceInstalledFont,monospace;">QUERYSTRING('path', 'value' as "&x", ' & ' as y, null as z) returns 'path?%26x=value&y=%20%26%20'</pre>
</div></div></td>
<td class='confluenceTd'>path, expr in {string}. name is an identifier</td>
</tr>
<tr>
<td class='confluenceTd'>REPEAT(str1,instances)</td>
<td class='confluenceTd'>Repeat string1 a specified number of times</td>
<td class='confluenceTd'>str1 in {string}, instances in {integer} return string</td>
</tr>
<tr>
<td class='confluenceTd'>RIGHT(x, y)</td>
<td class='confluenceTd'>Get right y characters of x</td>
<td class='confluenceTd'>x in {string}, y in {integer}, return string</td>
</tr>
<tr>
<td class='confluenceTd'>RPAD(input string x, pad length y)</td>
<td class='confluenceTd'>Pad input string x with spaces on the right to the length of y</td>
<td class='confluenceTd'>x in {string}, y in {integer}, return string</td>
</tr>
<tr>
<td class='confluenceTd'>RPAD(x, y, z)</td>
<td class='confluenceTd'>Pad input string x on the right to the length of y using character z</td>
<td class='confluenceTd'>x in {string}, y in {string}, z in {character}, return string</td>
</tr>
<tr>
<td class='confluenceTd'>RTRIM(x)</td>
<td class='confluenceTd'>Right trim x of blank chars</td>
<td class='confluenceTd'>x is string, return string</td>
</tr>
<tr>
<td class='confluenceTd'>SPACE(x)</td>
<td class='confluenceTd'>Repeat the space character x number of times</td>
<td class='confluenceTd'>x is integer, return string</td>
</tr>
<tr>
<td class='confluenceTd'>SUBSTRING(x, y)<br/>
SUBSTRING(x FROM y)</td>
<td class='confluenceTd'>[b] Get substring from x, from position y to the end of x</td>
<td class='confluenceTd'>y in {integer}</td>
</tr>
<tr>
<td class='confluenceTd'>SUBSTRING(x, y, z)<br/>
SUBSTRING(x FROM y FOR z)</td>
<td class='confluenceTd'>[b] Get substring from x from position y with length z</td>
<td class='confluenceTd'>y, z in {integer}</td>
</tr>
<tr>
<td class='confluenceTd'>TRANSLATE(x, y, z)</td>
<td class='confluenceTd'>Translate string x by replacing each character in y with the character in z at the same position</td>
<td class='confluenceTd'>x in {string}</td>
</tr>
<tr>
<td class='confluenceTd'>TRIM([[LEADING|TRAILING|BOTH] [x] FROM] y)</td>
<td class='confluenceTd'>Trim the leading, trailing, or both ends of a string y of character x. If LEADING/TRAILING/BOTH is not specified, BOTH is used. If no trim character x is specficed then the blank space ' ' is used.</td>
<td class='confluenceTd'>x in {character}, y in {string}</td>
</tr>
<tr>
<td class='confluenceTd'>UCASE(x)</td>
<td class='confluenceTd'>Uppercase of x</td>
<td class='confluenceTd'>x in {string}</td>
</tr>
<tr>
<td class='confluenceTd'>UNESCAPE(x)</td>
<td class='confluenceTd'>Unescaped version of x. Possible escape sequences are \b - backspace, \t - tab, \n - line feed, \f - form feed, \r - carriage return. \uXXXX, where X is a hex value, can be used to specify any unicode character. \XXX, where X is an octal digit, can be used to specify an octal byte value. If any other character appears after an escape character, that character will appear in the output and the escape character will be ignored.</td>
<td class='confluenceTd'>x in {string}</td>
</tr>
</tbody></table>
</div>
<p>[a] Non-ASCII range characters or integers used in these functions may produce different results or exceptions depending on where the function is evaluated (Teiid vs. source). Teiid's uses Java default int to char and char to int conversions, which operates over UTF16 values.</p>
<p>[b] The substring function depending upon the source does not have consistent behavior with respect to negative from/length arguments nor out of bounds from/length arguments. The default Teiid behavior is:</p>
<ul>
<li>return a null value when the from value is out of bounds or the length is less than 0</li>
<li>a zero from index is effective the same as 1.</li>
<li>a negative from index is first counted from the end of the string.</li>
</ul>
<p>Some sources however can return an empty string instead of null and some sources do not support negative indexing. If any of these inconsistencies impact you, then please log an issue.</p>
<h1><a name="StringFunctions-EncodingFunctions"></a>Encoding Functions</h1>
<h2><a name="StringFunctions-TOCHARS"></a>TO_CHARS</h2>
<p>Return a clob from the blob with the given encoding.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: sql; gutter: false" style="font-size:12px; font-family: ConfluenceInstalledFont,monospace;">TO_CHARS(x, encoding [, wellformed])</pre>
</div></div>
<p>BASE64, HEX, and the built-in Java Charset names are valid values for the encoding [b]. x is a blob, encoding is a string, wellformed is a boolean, and returns a clob. The two argument form defaults to wellformed=true. If wellformed is false, the conversion function will immediately validate the result such that an unmappable character or malformed input will raise an exception.</p>
<h2><a name="StringFunctions-TOBYTES"></a>TO_BYTES</h2>
<p>Return a blob from the clob with the given encoding.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: sql; gutter: false" style="font-size:12px; font-family: ConfluenceInstalledFont,monospace;">TO_BYTES(x, encoding [, wellformed])</pre>
</div></div>
<p>BASE64, HEX, and the builtin Java Charset names are valid values for the encoding [b]. x in a clob, encoding is a string, wellformed is a boolean and returns a blob. The two argument form defaults to wellformed=true. If wellformed is false, the conversion function will immediately validate the result such that an unmappable character or malformed input will raise an exception. If wellformed is true, then unmappable characters will be replaced by the default replacement character for the character set. Binary formats, such as BASE64 and HEX, will be checked for correctness regardless of the wellformed parameter.</p>
<p>[b] See the <a href="http://java.sun.com/j2se/1.5.0/docs/api/java/nio/charset/Charset.html" class="external-link" rel="nofollow">Charset JavaDoc</a> for more on supported Charset names.</p>
<h1><a name="StringFunctions-ReplacementFunctions"></a>Replacement Functions</h1>
<h2><a name="StringFunctions-REPLACE"></a>REPLACE</h2>
<p>Replace all occurrences of a given string with another.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: sql; gutter: false" style="font-size:12px; font-family: ConfluenceInstalledFont,monospace;">REPLACE(x, y, z)</pre>
</div></div>
<p>Replace all occurrences of y with z in x. x, y, z are strings and the return value is a string.</p>
<h2><a name="StringFunctions-REGEXPREPLACE"></a>REGEXP_REPLACE</h2>
<p>Replace one or all occurrences of a given pattern with another string.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: sql; gutter: false" style="font-size:12px; font-family: ConfluenceInstalledFont,monospace;">REGEXP_REPLACE(str, pattern, sub [, flags])</pre>
</div></div>
<p>Replace one or more occurrences of pattern with sub in str. All arguments are strings and the return value is a string.</p>
<p>The pattern parameter is expected to be a valid <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html" class="external-link" rel="nofollow">Java Regular Expression</a></p>
<p>The flags argument can be any concatenation of any of the valid flags with the following meanings:</p>
<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'>flag</th>
<th class='confluenceTh'>name</th>
<th class='confluenceTh'>meaning</th>
</tr>
<tr>
<td class='confluenceTd'>g</td>
<td class='confluenceTd'>global</td>
<td class='confluenceTd'>Replace all occurrences, not just the first</td>
</tr>
<tr>
<td class='confluenceTd'>m</td>
<td class='confluenceTd'>multiline</td>
<td class='confluenceTd'>Match over multiple lines</td>
</tr>
<tr>
<td class='confluenceTd'>i</td>
<td class='confluenceTd'>case insensitive</td>
<td class='confluenceTd'>Match without case sensitivity</td>
</tr>
</tbody></table>
</div>
<p>Usage:</p>
<p>The following will return "xxbye Wxx" using the global and case insensitive options.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>Example regexp_replace</b></div><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: sql; gutter: false" style="font-size:12px; font-family: ConfluenceInstalledFont,monospace;">
regexp_replace('Goodbye World', '[g-o].', 'x', 'gi')
</pre>
</div></div>
</div>
<div id="commentsSection" class="wiki-content pageSection">
<div style="float: right;" class="grey">
<a href="https://docs.jboss.org/author/users/removespacenotification.action?spaceKey=TEIID">Stop watching space</a>
<span style="padding: 0px 5px;">|</span>
<a href="https://docs.jboss.org/author/users/editmyemailsettings.action">Change email notification preferences</a>
</div>
<a href="https://docs.jboss.org/author/display/TEIID/String+Functions">View Online</a>
|
<a href="https://docs.jboss.org/author/pages/diffpagesbyversion.action?pageId=18646252&revisedVersion=15&originalVersion=14">View Changes</a>
|
<a href="https://docs.jboss.org/author/display/TEIID/String+Functions?showComments=true&showCommentArea=true#addcomment">Add Comment</a>
</div>
</div>
</div>
</div>
</div>
</body>
</html>