documented new script functions

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

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.