Fixed random_int and random_real functions; added random_boolean.

Split random_select into random_select and random_select_many.

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

doc/function/index.txt

@@ -14,6 +14,7 @@ These functions are built into the program, other [[type:function]]s can be defi
 | [[fun:abs]]			Absolute value
 | [[fun:random_int]]		Generate a random [[type:int]].
 | [[fun:random_real]]		Generate a random [[type:double]].
+| [[fun:random_boolean]]	Generate a random [[type:boolean]].
 	
 ! Text manipulation		<<<
 | [[fun:to_upper]]		Convert a string to upper case, @"aBc" -> "ABC"@.
@@ -44,7 +45,8 @@ These functions are built into the program, other [[type:function]]s can be defi
 | [[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.
+| [[fun:random_select]]		Pick a random element from a list.
+| [[fun:random_select_many]]	Pick multiple random elements from a list.
 	
 ! Keywords			<<<
 | [[fun:expand_keywords]]	Expand the keywords in a piece of text.

doc/function/random_boolean.txt

@@ -0,0 +1,22 @@
+Function: random_boolean
+
+DOC_MSE_VERSION: since 0.3.8
+
+--Usage--
+> random_boolean(probability)
+
+Returns a random [[type:bool]], either @true@ or @false.
+The parameter is the probability of returning @true@, so @random_boolean(0.0)@ always returns @true@, @random_boolean(1.0)@ always returns @false@ and @random_boolean(0.5)@ simulates a fair coin toss.
+
+Since the result is random, calling the function twice will give a different answer.
+
+--Parameters--
+! Parameter	Type		Default		Description
+| @input@	[[type:double]]	@0.5@		Probability of returining true
+
+--Examples--
+> random_boolean(0.5) == true
+> random_boolean(0.5) == false
+
+--See also--
+| [[fun:random_real]]		Generate a random [[type:double]].

doc/function/random_int.txt

@@ -23,3 +23,4 @@ Since the result is random, calling the function twice will give a different ans
 
 --See also--
 | [[fun:random_real]]		Generate a random [[type:double]].
+| [[fun:random_boolean]]	Generate a random [[type:boolean]].

doc/function/random_real.txt

@@ -22,3 +22,4 @@ Since the result is random, calling the function twice will give a different ans
 
 --See also--
 | [[fun:random_int]]		Generate a random [[type:int|integer number]].
+| [[fun:random_boolean]]	Generate a random [[type:boolean]].

doc/function/random_select.txt

@@ -5,28 +5,18 @@ 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).
+Randomly select an items from a list.
 
 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: false) == [1,3,4]
 
 --See also--
+| [[fun:random_select_many]]	Pick multiple random elements from a list.
 | [[fun:random_shuffle]]	Randomly shuffle a list.

doc/function/random_select_many.txt

@@ -0,0 +1,29 @@
+Function: random_select_many
+
+DOC_MSE_VERSION: since 0.3.8
+
+--Usage--
+> random_select(some_list, count: some_number, replace: some_boolean)
+
+Randomly select a number of items from a list.
+
+By default @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_many([1,2,3,4], count:3) == [2,3,1]
+> random_select_many([1,2,3,4], count:3) == [3,1,4]
+> random_select_many([1,2,3,4], count:3, replace: true)  == [2,3,2]
+> random_select_many([1,2,3,4], count:3, replace: false) == [1,3,4]
+
+--See also--
+| [[fun:random_select]]		Pick a single random element from a list.
+| [[fun:random_shuffle]]	Randomly shuffle a list.

doc/function/random_shuffle.txt

@@ -18,4 +18,5 @@ Since the result is random, calling the function twice will give a different ans
 > random_shuffle([1,2,3,4]) == [2,3,4,1]
 
 --See also--
-| [[fun:random_select]]		Pick random elements from a list.
+| [[fun:random_select]]		Pick a single random element from a list.
+| [[fun:random_select_many]]	Pick multiple random elements from a list.