documented new script functions

git-svn-id: svn://svn.code.sf.net/p/magicseteditor/code/trunk@1015 0fc631ac-6414-0410-93d0-97cfa31319b6

doc/function/abs.txt

@@ -0,0 +1,16 @@
+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

@@ -0,0 +1,25 @@
+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

@@ -0,0 +1,24 @@
+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

@@ -0,0 +1,32 @@
+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

@@ -0,0 +1,21 @@
+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

@@ -0,0 +1,25 @@
+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