documented new script functions

doc/function/abs.txt

+Function: abs
+
+DOC_MSE_VERSION: since 0.3.7
+
+--Usage--
+> abs(some_number)
+
+Returns the absolute value of a number.
+
+--Parameters--
+! Parameter	Type				Description
+| @input@	[[type:int]] or [[type:double]]	Number to determine the absolute value of
+
+--Examples--
+> abs(1.5) == 1.5
+> abs(-1)  == 1

doc/function/index.txt

@@ -6,9 +6,15 @@ These functions are built into the program, other [[type:function]]s can be defi
 | [[fun:to_string]]		Convert any value to a [[type:string]]
 | [[fun:to_int]]		Convert any value to a [[type:int]]
 | [[fun:to_real]]		Convert any value to a [[type:double]]
+| [[fun:to_number]]		Convert any value to a number
 | [[fun:to_boolean]]		Convert any value to a [[type:boolean]]
 | [[fun:to_color]]		Convert any value to a [[type:color]]
-
+	
+! Numbers			<<<
+| [[fun:abs]]			Absolute value
+| [[fun:random_int]]		Generate a random [[type:int]].
+| [[fun:random_real]]		Generate a random [[type:double]].
+	
 ! Text manipulation		<<<
 | [[fun:to_upper]]		Convert a string to upper case, @"aBc" -> "ABC"@.
 | [[fun:to_lower]]		Convert a string to lower case, @"aBc" -> "abc"@.
@@ -37,6 +43,8 @@ These functions are built into the program, other [[type:function]]s can be defi
 | [[fun:number_of_items]]	Return the number of items in a list.
 | [[fun:sort_list]]		Sort a list.
 | [[fun:filter_list]]		Filter a list, keeping only elements that match a predicate.
+| [[fun:random_shuffle]]	Randomly shuffle a list.
+| [[fun:random_select]]		Pick random elements from a list.
 	
 ! Keywords			<<<
 | [[fun:expand_keywords]]	Expand the keywords in a piece of text.

doc/function/random_int.txt

+Function: random_int
+
+DOC_MSE_VERSION: since 0.3.7
+
+--Usage--
+> random_int(begin: lower bound, end: upper bound)
+
+Returns a random [[type:int]] between @begin@ and @end@.
+By default @begin: 0@ is used.
+The random number @x@ will be in the range @begin <= x < end@.
+
+Since the result is random, calling the function twice will give a different answer.
+
+--Parameters--
+! Parameter	Type		Default		Description
+| @begin@	[[type:int]]	@0@		Lower end point of the range the number will be in.
+| @end@		[[type:int]]	''required''	Upper end point of the range the number will be in.
+
+--Examples--
+> random_int(end:10) == 2
+> random_int(end:10) == 5
+> random_int(begin:100, end:200) == 43
+
+--See also--
+| [[fun:random_real]]		Generate a random [[type:double]].

doc/function/random_real.txt

+Function: random_real
+
+DOC_MSE_VERSION: since 0.3.7
+
+--Usage--
+> random_real(begin: lower bound, end: upper bound)
+
+Returns a random [[type:double]] between @begin@ and @end@.
+By default the range @0.0@ to @1.0@ is used.
+
+Since the result is random, calling the function twice will give a different answer.
+
+--Parameters--
+! Parameter	Type		Default		Description
+| @begin@	[[type:double]]	@0.0@		Lower end point of the range the number will be in.
+| @end@		[[type:double]]	@1.0@		Upper end point of the range the number will be in.
+
+--Examples--
+> random_real() == 0.1451651461
+> random_real() == 0.7521351365
+> random_real(begin:100, end:200) == 193.2914351341
+
+--See also--
+| [[fun:random_int]]		Generate a random [[type:int|integer number]].

doc/function/random_select.txt

+Function: random_select
+
+DOC_MSE_VERSION: since 0.3.7
+
+--Usage--
+> random_select(some_list, count: some_number, replace: some_boolean)
+
+Randomly select a number of items from a list.
+
+If the @count@ parameter is not given, then a single item is picked at random.
+
+Otherwise @count@ ''different'' items are selected (selection without replacment).
+Setting the @replace@ parameter allows the same item to occur more than once in the result (selection with replacment).
+
+Since the result is random, calling the function twice will give a different answer.
+
+--Parameters--
+! Parameter	Type			Description
+| @input@	[[type:list]]		List to shuffle.
+| @count@	[[type:int]]		Number of items to select.
+| @replace@	[[type:boolean]]	Select with replacement?
+
+--Examples--
+> random_select([1,2,3,4]) == 4
+> random_select([1,2,3,4]) == 2
+> random_select([1,2,3,4], count:3) == [2,3,1]
+> random_select([1,2,3,4], count:3) == [3,1,4]
+> random_select([1,2,3,4], count:3, replace: true) == [2,3,2]
+> random_select([1,2,3,4], count:3, replace: true) == [1,3,4]
+
+--See also--
+| [[fun:random_shuffle]]	Randomly shuffle a list.

doc/function/random_shuffle.txt

+Function: random_shuffle
+
+DOC_MSE_VERSION: since 0.3.7
+
+--Usage--
+> random_shuffle(some_list)
+
+Randomly shuffle a list, putting the elements in a different order.
+
+Since the result is random, calling the function twice will give a different answer.
+
+--Parameters--
+! Parameter	Type			Description
+| @input@	[[type:list]]		List to shuffle.
+
+--Examples--
+> random_shuffle([1,2,3,4]) == [4,1,2,3]
+> random_shuffle([1,2,3,4]) == [2,3,4,1]
+
+--See also--
+| [[fun:random_select]]		Pick random elements from a list.

doc/function/to_int.txt

@@ -16,9 +16,11 @@ Convert any value to a [[type:int]].
 | @input@	''any type''		Value to convert to an integer number
 
 --Examples--
-> to_int(1.5)  == "1"
-> to_int("15") == "15"
-> to_int(true) == 1
+> to_int(1.5)   == "1"
+> to_int("15")  == "15"
+> to_int(true)  == 1
+> to_int(rgb(255,255,255)) == 255
 
 --See also--
 | [[fun:to_real]]		Convert any value to a [[type:double]]
+| [[fun:to_number]]		Convert any value to a number

doc/function/to_number.txt

+Function: to_number
+
+DOC_MSE_VERSION: since 0.3.7
+
+--Usage--
+> to_number(any value)
+
+Convert any value to a number.
+If the number can be represented as an [[type:int|integer number]] that is done.
+Otherwise it is converted to a [[type:double]].
+
+
+--Parameters--
+! Parameter	Type			Description
+| @input@	''any type''		Value to convert to a number
+
+--Examples--
+> to_number(1)     == 1
+> to_number(1.5)   == 1.5
+> to_number("1")   == 1
+> to_number("1.5") == 1.5
+
+--See also--
+| [[fun:to_int]]		Convert any value to a [[type:int]]
+| [[fun:to_real]]		Convert any value to a [[type:double]]

doc/function/to_real.txt

@@ -14,7 +14,8 @@ Convert any value to a [[type:double]].
 
 --Examples--
 > to_real(1)     == 1.0
-> to_real("1.5") == "1.5"
+> to_real("1.5") == 1.5
 
 --See also--
 | [[fun:to_int]]		Convert any value to a [[type:int]]
+| [[fun:to_number]]		Convert any value to a number

doc/script/index.txt

@@ -34,6 +34,7 @@ See also:
 | @a / b@		[[script:operators|Floating point division]]
 | @a div b@		[[script:operators|Integer division]]
 | @a mod b@		[[script:operators|Remainder]]
+| @a ^ b@		[[script:operators|Exponentiation]]
 | @not a@		[[type:boolean|Boolean not]]
 | @a and b@		[[type:boolean|Boolean conjunction]]
 | @a or b@		[[type:boolean|Boolean disjunction]]

doc/script/operators.txt

@@ -10,8 +10,11 @@ MSE script supports most basic mathamatical operators:
 | @a - b@	@3 - 2 == 1@		Substract two numbers
 | @a * b@	@3 * 2 == 6@		Multiply two numbers
 | @a / b@	@3 / 2   == 1.5@	Divide two numbers. Does not round, always produces a [[type:double]].
-| @a div b@	@3 div 2 == 1@		Divide two numbers. Rounds towards zero, producing an [[type:int]].<br/>
+| @a div b@	@3 div 2 == 1@		DOC_MSE_VERSION: since 0.3.7
+		 			Divide two numbers. Rounds towards zero, producing an [[type:int]].
 | @a mod b@	@3 mod 2 == 1@		Take the remainder after integer division (modulo)
+| @a ^ b@	@3 ^ 2 == 9@		DOC_MSE_VERSION: since 0.3.7
+		 			Exponentation, raise a to the power b.<br/> The numbers can be [[type:double]]s, so to calculate a square root use @2^0.5 == 1.41421356237@.
 | @-a@		@-(3 + 2) == -5@	Negate a number (make it negative if positive and vice versa)
 
 ===The + operator===