blob: ebf09884d2dc1df1046104c2bb81e4c350268ea8 [file] [log] [blame]
/*******************************************************************************
* Copyright © 2012, 2013 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* IBM Corporation - initial API and implementation
*
*******************************************************************************/
package eglx.lang;
import egl.lang.reflect.ParameterizableType;
import egl.lang.reflect.Operation;
import egl.lang.reflect.SequenceType;
externalType EString extends AnyText type ParameterizableType {
parameterizedType = SequenceType
}
/**
* Constructs an empty string.
*/
constructor();
/**
* {@Operation +} Concatenates two strings.
*/
static function $Plus(lvalue EString? in, rvalue EString? in) returns(EString) {@Operation{"+"}};
/**
* {@Operation ::} Concatenates two strings.
*/
static function $Concat(value EString? in, rvalue EString? in) returns (EString) {@Operation{"::"}};
/**
* {@Operation ?:} Concatenates two strings. If either is null then null is returned.
*/
static function $ConcatNull(value EString? in, rvalue EString? in) returns(EString?) {@Operation{"?:"}};
/**
* {@Operation <} Compares two strings.
*/
static function $LT(lvalue EString in, rvalue EString in) returns (EBoolean) {@Operation{"<"}};
/**
* {@Operation >} Compares two strings.
*/
static function $GT(lvalue EString in, rvalue EString in) returns (EBoolean) {@Operation{">"}};
/**
* {@Operation <=} Compares two strings.
*/
static function $LTE(lvalue EString in, rvalue EString in) returns (EBoolean) {@Operation{"<="}};
/**
* {@Operation >=} Compares two strings.
*/
static function $GTE(lvalue EString in, rvalue EString in) returns (EBoolean) {@Operation{">="}};
/**
* {@Operation ==} Compares two strings.
*/
static function $EQ(lvalue EString? in, rvalue EString? in) returns(EBoolean) {@Operation{"=="}};
/**
* {@Operation !=} Compares two strings.
*/
static function $NEQ(lvalue EString? in, rvalue EString? in) returns(EBoolean) {@Operation{"!="}};
/**
* {@Operation [:} Returns the substring starting at fromIndex and ending at toIndex.
* @throws InvalidIndexException if either index is out of range, or fromIndex is > toIndex.
*/
static function $Substr(value EString in, fromIndex EInt in, toIndex EInt in) returns(EString) {@Operation{"[:"}};
static function asNumber(value EString? in) returns(ENumber?) {@Operation{"narrow"}};
static function asString(value ENumber? in) returns (EString?) {@Operation{"widen"}};
/**
* {@Operation widen} Converts a bigint to a string. The string will consist of
* one or more digit characters. It will begin with a - sign if the value is
* negative.
*/
static function asString(value EBigint? in) returns (EString?) {@Operation{"widen"}};
/**
* {@Operation{"widen"} Converts a boolean to "true" or "false".
*/
static function asString(value EBoolean? in) returns (EString?) {@Operation{"widen"}};
/**
* {@Operation widen} Converts a date to a string in the format "MM/dd/yyyy".
* Leading zeros are included in the string, so April 1st in the year 9 A.D. is
* converted to "04/01/0009".
*/
static function asString(value EDate? in) returns (EString?) {@Operation{"widen"}};
/**
* {@Operation widen} Converts a decimal to a string. The string will consist of
* one or more digit characters, with a period used for a decimal point. The string
* will begin with a - sign if the value is negative.
*/
static function asString(value EDecimal? in) returns (EString?) {@Operation{"widen"}};
/**
* {@Operation widen} Converts a float to a string. The string will consist of
* one or more digit characters, with a period used for a decimal point. The string
* will begin with a - sign if the value is negative. It may end with an exponent,
* which is the letter e or E, followed by an optional negative sign, followed by one
* or more digit characters.
*/
static function asString(value EFloat? in) returns (EString?) {@Operation{"widen"}};
/**
* {@Operation widen} Converts an int to a string. The string will consist of
* one or more digit characters. It will begin with a - sign if the value is
* negative.
*/
static function asString(value EInt? in) returns (EString?) {@Operation{"widen"}};
/**
* {@Operation widen} Converts a smallfloat to a string. The string will consist of
* one or more digit characters, with a period used for a decimal point. The string
* will begin with a - sign if the value is negative. It may end with an exponent,
* which is the letter e or E, followed by an optional negative sign, followed by one
* or more digit characters.
*/
static function asString(value ESmallfloat? in) returns (EString?) {@Operation{"widen"}};
/**
* {@Operation widen} Converts a smallint to a string. The string will consist of
* one or more digit characters. It will begin with a - sign if the value is
* negative.
*/
static function asString(value ESmallint? in) returns (EString?) {@Operation{"widen"}};
/**
* {@Operation widen} Converts a timestamp to a string. The 26-character result
* will include all possible fields of a timestamp, from years down to fractions
* of seconds, in the format "yyyy-MM-dd HH:mm:ss.SSSSSS". Leading zeros are
* included in each field of the string when necessary, e.g. January is
* represented as "01" not "1".
*/
static function asString(value ETimestamp? in) returns (EString?) {@Operation{"widen"}};
/**
* {@Operation widen} Converts a time to a string. The result will be in the
* 24-hour format "HH:mm:ss". Leading zeros are included in each field of the string
* when necessary, e.g. 5 o'clock is represented as "05:00:00".
*/
static function asString(value ETime? in) returns (EString?) {@Operation{"widen"}};
/**
* Creates a string from the given bytes using the environment's default encoding.
*
* @param value the bytes to convert.
* @return the bytes as a string.
*/
static function fromBytes(value EBytes in) returns(EString);
/**
* Creates a string from the given bytes using the specified encoding.
*
* @param value the bytes to convert.
* @param encoding the encoding to use in the conversion.
* @return the bytes as a string.
* @throws InvalidArgumentException if the encoding is not supported.
*/
static function fromBytes(value EBytes in, encoding EString in) returns(EString);
/**
* Returns the environment's default encoding.
*
* @return the environment's default encoding.
*/
static function getDefaultEncoding() returns(EString);
/**
* A pattern-matching function which compares this string to a pattern using
* the rules of SQL's LIKE operator.
*
* This function makes its comparison character by character, left to right,
* and ends when one of the following conditions is met:
* - a character in this string fails to match a position in the regular expression (comparison is false)
* - one string ends but the other does not (comparison is false)
* - both strings end (comparison is true)
*This function ignores trailing blanks this string and the value parameter:
*
* There are three special characters:
* _ matches any one character
* % matches zero or more characters
* \ is the escape character
*
*
* @param value the pattern to compare with this string (also called the regular expression).
* @return true if this string matches the pattern.
* @throws InvalidPatternException if the pattern is invalid.
*/
function isLike(value EString in) returns(EBoolean);
/**
* A pattern-matching function which compares this string to a pattern using
* the rules of SQL's LIKE operator.
*
* This function makes its comparison character by character, left to right,
* and ends when one of the following conditions is met:
* - a character in this string fails to match a position in the regular expression (comparison is false)
* - one string ends but the other does not (comparison is false)
* - both strings end (comparison is true)
*This function ignores trailing blanks this string and the value parameter:
*
* There are three special characters:
* _ matches any one character
* % matches zero or more characters
* the escape character from the second parameter
*
* @param value the pattern to compare with this string (also called the regular expression).
* @param esc the escape character for the pattern.
* @return true if this string matches the pattern.
* @throws InvalidPatternException if the pattern is invalid.
*/
function isLike(value EString in, esc EString in) returns(EBoolean);
/**
* A pattern-matching function which compares this string to a pattern using
* the rules of Informix's MATCHES operator.
*
* This function makes its comparison character by character, left to right,
* and ends when one of the following conditions is met:
* - a character in this string fails to match a position in the regular expression (comparison is false)
* - one string ends but the other does not (comparison is false)
* - both strings end (comparison is true)
*
* You can include any of the following special characters in the regular expression:
* * Acts as a wildcard, matching zero or more characters in the string expression
* ? Acts as a wildcard, matching a single character in the string expression
* \ Acts as the escape character, causing an "escape" from the normal processing.
* For example, if you wanted to specify a regular expression that would be a valid
* match for the string "a*c", the regular expression would be:
* a\*c
* [ ] Any one of the characters between the two brackets is valid as a match for
* the next character in this string. For example, the following
* component of a regular expression indicates that a, b, or c is valid as a match:
* [abc]
* - Creates a range within the bracket delimiters, such that any character
* within the range is valid as a match for the next character in this string
* For example, the following component of a regular expression indicates
* that a, b, or c is valid as a match:
* [a-c]
* ^ The caret reverses the meaning of the bracket delimiters. Any character other
* than the delimited characters is valid as a match for the next character in this
* string. For example, the following component of a regular expression
* indicates that any character other than a, b, or c is valid as a match:
* [^abc]
*
* @param value the pattern to compare with this string (also called the regular expression).
* @return true if this string matches the pattern.
* @throws InvalidPatternException if the pattern is invalid.
*/
function matchesPattern(value EString in) returns(EBoolean);
/**
* A pattern-matching function which compares this string to a pattern using
* the rules of Informix's MATCHES operator.
*
* This function makes its comparison character by character, left to right,
* and ends when one of the following conditions is met:
* - a character in this string fails to match a position in the regular expression (comparison is false)
* - one string ends but the other does not (comparison is false)
* - both strings end (comparison is true)
*
* You can include any of the following special characters in the regular expression:
* * Acts as a wildcard, matching zero or more characters in the string expression
* ? Acts as a wildcard, matching a single character in the string expression
* [ ] Any one of the characters between the two brackets is valid as a match for
* the next character in this string. For example, the following
* component of a regular expression indicates that a, b, or c is valid as a match:
* [abc]
* - Creates a range within the bracket delimiters, such that any character
* within the range is valid as a match for the next character in this string
* For example, the following component of a regular expression indicates
* that a, b, or c is valid as a match:
* [a-c]
* ^ The caret reverses the meaning of the bracket delimiters. Any character other
* than the delimited characters is valid as a match for the next character in this
* string. For example, the following component of a regular expression
* indicates that any character other than a, b, or c is valid as a match:
* [^abc]
*
* @param value the pattern to compare with this string (also called the regular expression).
* @param esc the escape character for the pattern (see description of the escape
* character in the previous function).
* @return true if this string matches the pattern.
* @throws InvalidPatternException if the pattern is invalid.
*/
function matchesPattern(value EString in, esc EString in) returns(EBoolean);
/**
* Returns the number of characters in this string.
*
* @return the length of this string.
*/
function length() returns(EInt);
/**
* Returns this string minus any trailing blanks.
*
* @return the clipped string.
*/
function clip() returns(EString);
/**
* Returns this string minus any leading blanks.
*
* @return the clipped string.
*/
function clipLeading() returns(EString);
/**
* Returns this string minus any leading and trailing blanks.
*
* @return the trimmed string.
*/
function trim() returns(EString);
/**
* Returns this string with its characters converted to upper case.
*
* @return the uppercased string.
*/
function toUpperCase() returns(EString);
/**
* Returns this string with its characters converted to lower case.
*
* @return the lowercased string.
*/
function toLowerCase() returns(EString);
/**
* Searches for a substring within this string, starting at index 1,
* and returns the index of its first character.
*
* @param substr the substring to find.
* @return the index of the substring, or 0 if it wasn't found.
*/
function indexOf(substr EString in) returns (EInt);
/**
* Searches for a substring within this string, starting at the given index,
* and returns the index of its first character.
*
* @param substr the substring to find.
* @param startIndex where to start the search.
* @return the index of the substring, or 0 if it wasn't found.
* @throws InvalidIndexException if startIndex is less than 1 or greater
* than the length of this string.
*/
function indexOf(substr EString in, startIndex EInt in) returns (EInt);
/**
* Searches for a substring within this string, starting at the end, and
* returns the index of its first character.
*
* @param substr the substring to find.
* @return the index of the substring, or 0 if it wasn't found.
*/
function lastIndexOf(substr EString in) returns (EInt);
/**
* Tells if this string ends with the given substring.
*
* @param suffix the suffix to find.
* @return true if the substring appears at the end of this string.
*/
function endsWith(suffix EString in) returns(EBoolean);
/**
* Tells if this string starts with the given substring.
*
* @param prefix the prefix to find.
* @return true if the substring appears at the front of this string.
*/
function startsWith(prefix EString in) returns(EBoolean);
/**
* Returns a string created by replacing all occurances of one substring with
* another. The target substring and its replacement may have different lengths.
*
* @param target the substring to find.
* @param replacement the replacement for the target substring.
* @return this string, with replacements.
*/
function replaceStr(target EString in, replacement EString in) returns(EString);
/**
* Returns the Unicode codepoint of the given character, as an int.
*
* @param index the index of the character.
* @return the Unicode codepoint of the given character, as an int.
* @throws InvalidIndexException if index is less than 1 or greater
* than the length of this string.
*/
function charCodeAt(index EInt in) returns(EInt);
/**
* Converts this string as bytes using the environment's default encoding.
*
* @return this string as bytes.
*/
function toBytes() returns(EBytes);
/**
* Converts this string as bytes using the given encoding.
*
* @param encoding the encoding to use in the conversion.
* @return this string as bytes.
* @throws InvalidArgumentException if the encoding is not supported.
*/
function toBytes(encoding EString in) returns(EBytes);
/**
* Creates a string from a list of strings, with a separator between them.
*/
static function join( separator EString in, strings EString[] in ) returns( EString );
/**
* Returns an array containing substrings of this string. The 'separator'
* parameter indicates where each substring ends. If the separator is not
* contained in this string, then the result contains only this string.
*/
function split( separator EString in ) returns( EString[] );
/**
* Same as the other version of split, except the size of the result will not
* be larger than the specified limit. Returns an empty array if limit is less than one.
*/
function split( separator EString in, limit EInt in ) returns( EString[] );
/**
* This is like split(string), except the returned substrings are separated by
* characters that match the specified pattern (see the matchesPattern
* function).
*/
function splitOnPattern( pattern EString in ) returns( EString[] );
/**
* This is the same as splitOnPattern(EString), but the additional parameter
* specifies the escape character used in the pattern.
*/
function splitOnPattern( pattern EString in, escape EString in ) returns( EString[] );
/**
* Same as the other version of splitOnPattern, except the size of the result will not
* be larger than the specified limit. Returns an empty array if limit is less than one.
*/
function splitOnPattern( pattern EString in, limit EInt in ) returns( EString[] );
/**
* This is the same as splitOnPattern(EString,EInt), but the additional parameter
* specifies the escape character used in the pattern.
*/
function splitOnPattern( pattern EString in, escape EString in, limit EInt in ) returns( EString[] );
/**
* Returns a reversed copy of this string.
*/
function reverse() returns( EString );
/**
* Does a case-insensitive comparison of two strings. Returns a negative
* number, zero, or a positive number to indicate that this string is less
* than, equal to, or greater than the other string.
*/
function compareIgnoreCase( str EString in ) returns( EInt );
/**
* Makes a new string containing the characters of this string, with a second
* string inserted somewhere in the middle.
* str1.insert(offset, str2) is equivalent to
* str1[1:offset] :: str2 :: str1[offset:str1.length()]
*
* @throws InvalidIndexException if offset is less than 1 or greater
* than the length of this string.
*/
function insertStr( offset EInt in, str EString in ) returns( EString );
/**
* Makes a new string containing the characters of this string, with a section
* replaced by a second string.
* str1.replaceStrAt(start, end, str2) is equivalent to
* str1[1:start] :: str2 :: str1[end:str1.length()]
*
* @throws InvalidIndexException if startIndex is less than 1, greater
* than the length of this string, or greater than endIndex.
* @throws InvalidIndexException if endIndex is greater than the length
* of this string.
*/
function replaceStrAt( startIndex EInt in, endIndex EInt in, str EString in ) returns( EString );
/**
* This is like the indexOf function, except we look for a pattern (as defined
* for the matchesPattern function) instead of a literal substring.
*/
function indexOfPattern( pattern EString in ) returns( EInt );
/**
* This is the same as indexOfPattern(EString), but the additional parameter
* specifies the escape character used in the pattern.
*/
function indexOfPattern( pattern EString in, escape EString in ) returns( EInt );
/**
* This is like the indexOf function, except we look for a pattern (as defined
* for the matchesPattern function) instead of a literal substring.
*
* @throws InvalidIndexException if startIndex is less than 1 or greater
* than the length of this string.
*/
function indexOfPattern( pattern EString in, startIndex EInt in ) returns( EInt );
/**
* This is the same as indexOfPattern(EString,EInt), but the additional parameter
* specifies the escape character used in the pattern.
*/
function indexOfPattern( pattern EString in, escape EString in, startIndex EInt in ) returns( EInt );
/**
* Returns a string made by searching this string for the pattern (as defined
* for the matchesPattern function), and substituting the replacement string
* where a match is found. All matches will be replaced if the 'global'
* parameter is true, otherwise only the first match is replaced. If the
* pattern is not matched, then this string is returned.
*/
function replacePattern( pattern EString in, replacement EString in, global EBoolean in ) returns( EString );
/**
* This is the same as replacePattern(EString,EString,EBoolean), but the additional parameter
* specifies the escape character used in the pattern.
*/
function replacePattern( pattern EString in, escape EString in, replacement EString in, global EBoolean in ) returns( EString );
/**
* Returns true if this string's length is zero.
*/
function isEmpty() returns( EBoolean );
end