added String specification

std/Array.hx

@@ -152,7 +152,7 @@ extern class Array<T> {
 		If [len] is < 0 or [pos] exceeds [this].length, the result is the empty
 		Array [].
 		
-		If [pos] is negative, its values is calculated from the end	of [this]
+		If [pos] is negative, its value is calculated from the end	of [this]
 		Array by [this].length + [pos]. If this yields a negative value, 0 is
 		used instead.
 		

std/String.hx

@@ -21,11 +21,19 @@
  */
 /**
 	The basic String class.
+	
+	A haxe String is immutable, it is not possible to modify individual
+	characters. No method of this class changes the state of [this] String.
+	
+	Strings can be constructed using the string literal syntax "string value".
+	
+	String can be concatenated by using the + operator. If an operand is not a
+	String, it is passed through Std.string() first.
 **/
 extern class String {
 
 	/**
-		The number of characters in the String.
+		The number of characters in [this] String.
 	**/
 	var length(default,null) : Int;
 
@@ -35,56 +43,105 @@ extern class String {
 	function new(string:String) : Void;
 
 	/**
-		Returns an String where all characters have been uppercased.
+		Returns a String where all characters of [this] String are upper case.
+		
+		Affects the characters [a-z]. Other characters remain unchanged.
 	**/
 	function toUpperCase() : String;
 
 	/**
-		Returns an String where all characters have been lowercased.
+		Returns a String where all characters of [this] String are lower case.
+		
+		Affects the characters [A-Z]. Other characters remain unchanged.
 	**/
 	function toLowerCase() : String;
 
 	/**
-		Returns the character at the given position.
-		Returns the empty String if outside of String bounds.
+		Returns the character at position [index] of [this] String.
+		
+		If [index] is negative or exceeds [this].length, the empty String ""
+		is returned.
 	**/
-	function charAt( index : Int) : String;
+	function charAt(index : Int) : String;
 
 	/**
-		Returns the character code at the given position.
-		Returns [null] if outside of String bounds.
+		Returns the character code at position [index] of [this] String.
+		
+		If [index] is negative or exceeds [this].length, null is returned.
+		
+		To obtain the character code of a single character, "x".code can be used
+		instead to inline the character code at compile time. Note that this
+		only works on String literals of length 1.
 	**/
 	function charCodeAt( index : Int) : Null<Int>;
 
 	/**
-		Returns the index of first occurence of [value]
-		Returns [1-1] if [value] is not found.
-		The optional [startIndex] parameter allows you to specify at which character to start searching.
-		The position returned is still relative to the beginning of the string.
+		Returns the position of the leftmost occurence of [str] within [this]
+		String.
+		
+		If [startIndex] is given, the search is performed within the substring
+		of [this] String starting from [startIndex]. Otherwise the search is
+		performed within [this] String. In either case, the returned position
+		is relative to the beginning of [this] String.
+		
+		If [str] cannot be found, -1 is returned.
 	**/
 	function indexOf( str : String, ?startIndex : Int ) : Int;
 
 	/**
-		Similar to [indexOf] but returns the latest index.
+		Returns the position of the rightmost occurence of [str] within [this]
+		String.
+		
+		If [startIndex] is given, the search is performed within the substring
+		of [this] String from 0 to [startIndex]. Otherwise the search is
+		performed within [this] String. In either case, the returned position
+		is relative to the beginning of [this] String.
+		
+		If [str] cannot be found, -1 is returned.
 	**/
 	function lastIndexOf( str : String, ?startIndex : Int ) : Int;
 
 	/**
-		Split the string using the specified delimiter.
+		Splits [this] String at each occurence of [delimiter].
+		
+		If [delimiter] is the empty String "", [this] String is split into an
+		Array of [this].length elements, where the elements correspond to the
+		characters of [this] String.
+		
+		If [delimiter] is not found within [this] String, the result is an Array
+		with one element, which equals [this] String.
+		
+		If [delimiter] is null, the result is unspecified.
+		
+		Otherwise, [this] String is split into parts at each occurence of
+		[delimiter]. If [this] String starts (or ends) with [delimiter}, the
+		result Array contains a leading (or trailing) empty String "" element.
+		Two subsequent delimiters also result in an empty String "" element.
 	**/
 	function split( delimiter : String ) : Array<String>;
 
 	/**
-		Returns a part of the String, taking [len] characters starting from [pos].
-		If [len] is not specified, it takes all the remaining characters.
+		Returns [len] characters of [this] String, starting at position [pos].
+		
+		If [len] is omitted, all characters from position [pos] to the end of
+		[this] String are included.
+		
+		If [pos] is negative, its values is calculated from the end	of [this]
+		String by [this].length + [pos]. If this yields a negative value, 0 is
+		used instead.
+		
+		If [len] is negative, the result is unspecified.
 	**/
 	function substr( pos : Int, ?len : Int ) : String;
 
 	/**
-		Returns a part of the String, taking from [startIndex] to [endIndex] - 1.
-		If [endIndex] is not specified, length is used.
-		If [startIndex] or [endIndex] is smaller than 0, than 0 is used.
-		If [startIndex] > [endIndex] then they are swaped.
+		Returns the part of [this] String from [startIndex] to [endIndex].
+		
+		If [endIndex] is omitted, [this].length is used instead.
+		
+		If [startIndex] or [endIndex] are negative, 0 is used instead.
+		
+		If [startIndex] exceeds [endIndex], they are swapped.
 	**/
 	function substring( startIndex : Int, ?endIndex : Int ) : String;
 
@@ -93,6 +150,11 @@ extern class String {
 	**/
 	function toString() : String;
 
+	/**
+		Returns the String corresponding to the character code [code].
+		
+		If [code] is negative or has another invalid value, the result is
+		unspecified.
+	**/	
 	static function fromCharCode( code : Int ) : String;
-
-}
+}

tests/unit/unitstd/String.unit.hx

@@ -0,0 +1,152 @@
+// new
+var str = "foo";
+var str2 = new String(str);
+str == str2;
+
+// toUpperCase
+"foo".toUpperCase() == "FOO";
+"_bar".toUpperCase() == "_BAR";
+"123b".toUpperCase() == "123B";
+"".toUpperCase() == "";
+"A".toUpperCase() == "A";
+
+// toLowerCase
+"FOO".toLowerCase() == "foo";
+"_BAR".toLowerCase() == "_bar";
+"123B".toLowerCase() == "123b";
+"".toLowerCase() == "";
+"a".toLowerCase() == "a";
+
+// charAt
+var s = "foo1bar";
+s.charAt(0) == "f";
+s.charAt(1) == "o";
+s.charAt(2) == "o";
+s.charAt(3) == "1";
+s.charAt(4) == "b";
+s.charAt(5) == "a";
+s.charAt(6) == "r";
+s.charAt(7) == "";
+s.charAt( -1) == "";
+"".charAt(0) == "";
+"".charAt(1) == "";
+"".charAt( -1) == "";
+
+// charCodeAt
+var s = "foo1bar";
+s.charCodeAt(0) == 102;
+s.charCodeAt(1) == 111;
+s.charCodeAt(2) == 111;
+s.charCodeAt(3) == 49;
+s.charCodeAt(4) == 98;
+s.charCodeAt(5) == 97;
+s.charCodeAt(6) == 114;
+s.charCodeAt(7) == null;
+s.charCodeAt( -1) == null;
+
+// code
+"f".code == 102;
+"o".code == 111;
+"1".code == 49;
+"b".code == 98;
+"a".code == 97;
+"r".code == 114;
+
+// indexOf
+var s = "foo1bar";
+s.indexOf("f") == 0;
+s.indexOf("o") == 1;
+s.indexOf("1") == 3;
+s.indexOf("b") == 4;
+s.indexOf("a") == 5;
+s.indexOf("r") == 6;
+s.indexOf("z") == -1;
+//s.indexOf(null) == -1;
+//s.indexOf(null, 1) == -1;
+//s.indexOf(null, -1) == -1;
+s.indexOf("foo") == 0;
+s.indexOf("oo") == 1;
+//s.indexOf("bart") == -1;
+//s.indexOf("r", -1) == -1;
+//s.indexOf("r", -10) == -1;
+s.indexOf("o", 1) == 1;
+s.indexOf("o", 2) == 2;
+s.indexOf("o", 3) == -1;
+
+// lastIndexOf
+var s = "foofoofoobarbar";
+s.lastIndexOf("r") == 14;
+s.lastIndexOf("a") == 13;
+s.lastIndexOf("b") == 12;
+s.lastIndexOf("bar") == 12;
+s.lastIndexOf("foo") == 6;
+s.lastIndexOf("foofoo") == 3;
+s.lastIndexOf("f") == 6;
+s.lastIndexOf("barb") == 9;
+s.lastIndexOf("z") == -1;
+//s.lastIndexOf(null) == -1;
+//s.lastIndexOf(null, 1) == -1;
+//s.lastIndexOf(null, 14) == -1;
+s.lastIndexOf("r", 14) == 14;
+s.lastIndexOf("r", 13) == 11;
+s.lastIndexOf("a", 14) == 13;
+s.lastIndexOf("a", 13) == 13;
+s.lastIndexOf("a", 12) == 10;
+s.lastIndexOf("bar", 12) == 12;
+s.lastIndexOf("bar", 11) == 9;
+s.lastIndexOf("bar", 9) == 9;
+s.lastIndexOf("bar", 8) == -1;
+
+// split
+var s = "xfooxfooxxbarxbarxx";
+s.split("x") == ["", "foo", "foo", "", "bar", "bar", "",""];
+s.split("xx") == ["xfooxfoo","barxbar",""];
+s.split("") == ["x", "f", "o", "o", "x", "f", "o", "o", "x", "x", "b", "a", "r", "x", "b", "a", "r", "x", "x"];
+s.split("z") == ["xfooxfooxxbarxbarxx"];
+
+// substr
+var s = "xfooxfooxxbarxbarxx";
+s.substr(0) == "xfooxfooxxbarxbarxx";
+s.substr(1) == "fooxfooxxbarxbarxx";
+s.substr(19) == "";
+s.substr(18) == "x";
+s.substr(17) == "xx";
+s.substr(-1) == "x";
+s.substr(-2) == "xx";
+s.substr(-18) == "fooxfooxxbarxbarxx";
+s.substr(-19) == "xfooxfooxxbarxbarxx";
+s.substr( -100) == "xfooxfooxxbarxbarxx";
+s.substr(0, 0) == "";
+s.substr(0, 1) == "x";
+s.substr(0, 2) == "xf";
+s.substr(0, 100) == "xfooxfooxxbarxbarxx";
+s.substr(0, -1) == "xfooxfooxxbarxbarx";
+s.substr(0, -2) == "xfooxfooxxbarxbar";
+s.substr(1, -2) == "fooxfooxxbarxbar";
+s.substr(2, -2) == "ooxfooxxbarxbar";
+s.substr(0, -100) == "";
+
+// substring
+var s = "xfooxfooxxbarxbarxx";
+s.substring(0, 0) == "";
+s.substring(0, 1) == "x";
+s.substring(1, 0) == "x";
+s.substring(0, 2) == "xf";
+s.substring(2, 0) == "xf";
+s.substring(-1, 0) == "";
+s.substring(0, -1) == "";
+s.substring(-1, -1) == "";
+s.substring(-1, 1) == "x";
+s.substring(1, -1) == "x";
+s.substring(-1, 2) == "xf";
+s.substring(2, -1) == "xf";
+s.substring(0) == "xfooxfooxxbarxbarxx";
+s.substring(1) == "fooxfooxxbarxbarxx";
+s.substring(2) == "ooxfooxxbarxbarxx";
+s.substring(0, -1) == "";
+s.substring(1, -1) == "x";
+s.substring(2, -1) == "xf";
+s.substring(20, 0) == "xfooxfooxxbarxbarxx";
+
+// fromCharCode
+String.fromCharCode(65) == "A";