add query sort closure examples (#1030)

* add closure examples

Author: zspitzer

docs/03.reference/01.functions/arraysort/_arguments/locale_sensitive.md

@@ -1 +1 @@
-if true it does a locale sensitive sorting.
+if true, use locale sensitive sorting.

docs/03.reference/01.functions/arraysort/_arguments/sorttype_or_closure.md

@@ -7,6 +7,9 @@ a string must be one of the following values:
 - "textnocase": sorts text alphabetically, without regard to case (case insensitive)
 
 if you define a closure/function, the closure/function must accept 2 parameters of any type and return:
-\-1, if first parameter is "smaller" than second parameter
-0, if first parameter is equal to second parameter
-1, first parameter is "bigger" than second parameter
+
+- \-1, if first parameter is "smaller" than second parameter
+- 0, if first parameter is equal to second parameter
+- 1, first parameter is "bigger" than second parameter
+
+`function (any e1, any e2) { return -1/0/1;});`

docs/03.reference/01.functions/querysort/_arguments/columnNameOrSortFunc.md

@@ -1 +1,5 @@
-a list of names, a single column name or a function used as comparator.
+- a list of names
+- a single column name
+- or a function used as comparator with the following constructor
+
+`function(struct row1, struct row2){ return true / false;}`.

docs/03.reference/01.functions/querysort/_arguments/direction.md

@@ -1 +1,5 @@
-a list of directions or a single direction definition (asc,desc), the list must have the same length as the columnName list
+A list of directions or a single direction definition (asc, desc), 
+
+The list must have the same length as the columnName list.
+
+Only used when the second argument defines a list of column names.

docs/03.reference/01.functions/querysort/_examples.md

@@ -1,33 +1,19 @@
 ```luceescript+trycf
 people = QueryNew( "name,dob,age", "varchar,date,int", [
-    [ "Susi", CreateDate( 1970, 1, 1 ), 0 ],
-    [ "Urs" , CreateDate( 1995, 1, 1 ), 0 ],
-    [ "Fred", CreateDate( 1960, 1, 1 ), 0 ],
-    [ "Jim" , CreateDate( 1988, 1, 1 ), 0 ]
+    [ "Susi", CreateDate( 1970, 1, 1 ), 70 ],
+    [ "Urs" , CreateDate( 1995, 1, 1 ), 40 ],
+    [ "Fred", CreateDate( 1960, 1, 1 ), 50 ],
+    [ "Jim" , CreateDate( 1988, 1, 1 ), 30 ]
 ]);
 
-Dump( var=people, label="people - origional query" );
+Dump( var=people, label="people - original query" );
 
-/* Output:
-
-| name | dob                 | age |
-------------------------------------
-| Susi | 1970-01-01 00:00:00 | 0   |
-| Urs  | 1995-01-01 00:00:00 | 0   |
-| Fred | 1960-01-01 00:00:00 | 0   |
-| Jim  | 1988-01-01 00:00:00 | 0   |
-*/
-
-people.sort('name', 'asc');
+QuerySort(people, 'name', 'asc');
 dump(var=people, label='people - sorted by name');
 
-/* Output:
+QuerySort(people, function(row1, row2){
+	return compare(arguments.row1.age, arguments.row2.age);
+});
+dump(var=people, label='people - sorted by age');
 
-| name | dob                 | age |
-------------------------------------
-| Fred | 1960-01-01 00:00:00 | 0   |
-| Jim  | 1988-01-01 00:00:00 | 0   |
-| Susi | 1970-01-01 00:00:00 | 0   |
-| Urs  | 1995-01-01 00:00:00 | 0   |
-*/
-```
+```

docs/03.reference/05.objects/array/sort/_arguments/locale_sensitive.md

@@ -1 +1 @@
-if true it does a locale sensitive sorting.
+if true, use locale sensitive sorting.

docs/03.reference/05.objects/array/sort/_arguments/sorttype_or_closure.md

@@ -8,6 +8,8 @@ a string must be one of the following values:
 
 if you define a closure/function, the closure/function must accept 2 parameters of any type and return:
 
--1, if first parameter is "smaller" than second parameter
-0, if first parameter is equal to second parameter
-1, first parameter is "bigger" than second parameter
+- -1, if first parameter is "smaller" than second parameter
+- 0, if first parameter is equal to second parameter
+- 1, first parameter is "bigger" than second parameter
+
+`function (any e1, any e2) { return -1/0/1;});`

docs/03.reference/05.objects/query/sort/_arguments/columnNameOrSortFunc.md

@@ -1 +1,5 @@
-a list of names, a single column name or a function used as comparator.
+- a list of names
+- a single column name
+- or a function used as comparator with the following constructor
+
+`function(struct row1, struct row2){ return true / false;}`.

docs/03.reference/05.objects/query/sort/_arguments/direction.md

@@ -1 +1,5 @@
-a list of directions or a single direction definition (asc,desc), the list must have the same length as the columnName list. ONly used when the second argument defines a list of column names.
+a list of directions or a single direction definition (asc, desc), 
+
+the list must have the same length as the columnName list. 
+
+Only used when the second argument defines a list of column names.

docs/03.reference/05.objects/query/sort/_examples.md

@@ -1,12 +1,19 @@
-
 ```luceescript+trycf
-news = queryNew("id,items",
-    "integer,varchar",
-    [ {"id":1,"items":"chocolate"}, {"id":2,"items":"juice"}, {"id":3,"items":"vegitable"} ]);
-//sort it
-news.sort("items","desc");
-//dump it
-writeDump(news);
-news.sort("items","asc");
-writeDump(news);
+people = QueryNew( "name,dob,age", "varchar,date,int", [
+    [ "Susi", CreateDate( 1970, 1, 1 ), 70 ],
+    [ "Urs" , CreateDate( 1995, 1, 1 ), 40 ],
+    [ "Fred", CreateDate( 1960, 1, 1 ), 50 ],
+    [ "Jim" , CreateDate( 1988, 1, 1 ), 30 ]
+]);
+
+Dump( var=people, label="people - original query" );
+
+people.sort('name', 'asc');
+dump(var=people, label='people - sorted by name');
+
+people2 = people.sort(function(row1, row2){
+	return compare(arguments.row1.age, arguments.row2.age);
+});
+dump(var=people2, label='people - sorted by age');
+
 ```