update docs for tuples

Author: vincentlauvlwj

README_cn.md

@@ -401,12 +401,12 @@ val employees = database.employees.toCollection(ArrayList())
 val names = database.employees.mapColumns { it.name }
 ```
 
-除此之外，还有 `mapColumns2`、`mapColumns3` 等更多函数，它们用来同时获取多个列的结果，这时我们需要在闭包中使用 `Pair` 或 `Triple` 包装我们的这些字段，函数的返回值也相应变成了 `List<Pair<C1?, C2?>>` 或 `List<Triple<C1?, C2?, C3?>>`：
+除此之外，`mapColumns` 还可以同时获取多个列的结果，这时我们只需要在闭包中使用 `tupleOf` 包装我们的这些字段，函数的返回值也相应变成了 `List<TupleN<C1?, C2?, .. Cn?>>`：
 
 ```kotlin
 database.employees
     .filter { it.departmentId eq 1 }
-    .mapColumns2 { Pair(it.id, it.name) }
+    .mapColumns { tupleOf(it.id, it.name) }
     .forEach { (id, name) ->
         println("$id:$name")
     }
@@ -438,12 +438,12 @@ val max = database.employees
     .aggregateColumns { max(it.salary) }
 ```
 
-如果你希望同时获取多个聚合结果，可以改用 `aggregateColumns2` 或 `aggregateColumns3` 函数，这时我们需要在闭包中使用 `Pair` 或 `Triple` 包装我们的这些聚合表达式，函数的返回值也相应变成了 `Pair<C1?, C2?>` 或 `Triple<C1?, C2?, C3?>`。下面的例子获取部门 1 中工资的平均值和极差：
+如果你希望同时获取多个聚合结果，只需要在闭包中使用 `tupleOf` 包装我们的这些聚合表达式即可，此时函数的返回值就相应变成了 `Pair<C1?, C2?, .. Cn?>`。下面的例子获取部门 1 中工资的平均值和极差：
 
 ```kotlin
 val (avg, diff) = database.employees
     .filter { it.departmentId eq 1 }
-    .aggregateColumns2 { Pair(avg(it.salary), max(it.salary) - min(it.salary)) }
+    .aggregateColumns { tupleOf(avg(it.salary), max(it.salary) - min(it.salary)) }
 ```
 
 生成 SQL：

ktorm-core/generate-tuples.gradle

@@ -129,6 +129,9 @@ def generateMapColumns(Writer writer, int tupleNumber) {
          * element. Besides, the function’s return type is a tuple of `ColumnDeclaring<C>`s, and we should return some 
          * columns or expressions to customize the `select` clause of the generated SQL.
          *
+         * Ktorm supports selecting two or more columns, we just need to wrap our selected columns by [tupleOf]
+         * in the closure, then the function’s return type becomes `List<TupleN<C1?, C2?, .. Cn?>>`.
+         *
          * The operation is terminal.
          *
          * @param isDistinct specify if the query is distinct, the generated SQL becomes `select distinct` if it's set to true.
@@ -155,6 +158,9 @@ def generateMapColumns(Writer writer, int tupleNumber) {
          * element. Besides, the function’s return type is a tuple of `ColumnDeclaring<C>`s, and we should return some 
          * columns or expressions to customize the `select` clause of the generated SQL.
          * 
+         * Ktorm supports selecting two or more columns, we just need to wrap our selected columns by [tupleOf]
+         * in the closure, then the function’s return type becomes `List<TupleN<C1?, C2?, .. Cn?>>`.
+         *
          * The operation is terminal.
          *
          * @param destination a [MutableCollection] used to store the results.
@@ -214,6 +220,9 @@ def generateAggregateColumns(Writer writer, int tupleNumber) {
          * Perform a tuple of aggregations given by [aggregationSelector] for all elements in the sequence,
          * and return the aggregate results.
          *
+         * Ktorm supports aggregating two or more columns, we just need to wrap our aggregate expressions by
+         * [tupleOf] in the closure, then the function’s return type becomes `TupleN<C1?, C2?, .. Cn?>`.
+         *
          * The operation is terminal.
          *
          * @param aggregationSelector a function that accepts the source table and returns a tuple of aggregate expressions.
@@ -302,6 +311,9 @@ def generateGroupingAggregateColumns(Writer writer, int tupleNumber) {
          * The key for each group is provided by the [EntityGrouping.keySelector] function, and the generated SQL is like:
          * `select key, aggregation from source group by key`.
          *
+         * Ktorm supports aggregating two or more columns, we just need to wrap our aggregate expressions by [tupleOf]
+         * in the closure, then the function’s return type becomes `Map<K?, TupleN<C1?, C2?, .. Cn?>>`.
+         *
          * @param aggregationSelector a function that accepts the source table and returns a tuple of aggregate expressions.
          * @return a [Map] associating the key of each group with the results of aggregations of the group elements.
          * @since 3.1.0
@@ -322,6 +334,9 @@ def generateGroupingAggregateColumns(Writer writer, int tupleNumber) {
          * The key for each group is provided by the [EntityGrouping.keySelector] function, and the generated SQL is like:
          * `select key, aggregation from source group by key`.
          *
+         * Ktorm supports aggregating two or more columns, we just need to wrap our aggregate expressions by [tupleOf]
+         * in the closure, then the function’s return type becomes `Map<K?, TupleN<C1?, C2?, .. Cn?>>`.
+         *
          * @param destination a [MutableMap] used to store the results.
          * @param aggregationSelector a function that accepts the source table and returns a tuple of aggregate expressions.
          * @return the [destination] map associating the key of each group with the result of aggregations of the group elements.

ktorm-core/src/main/kotlin/me/liuwj/ktorm/entity/EntityGrouping.kt

@@ -82,9 +82,8 @@ public class EntityGrouping<E : Any, T : BaseTable<E>, K : Any>(
  * The key for each group is provided by the [EntityGrouping.keySelector] function, and the generated SQL is like:
  * `select key, aggregation from source group by key`.
  *
- * Ktorm also supports aggregating two or more columns, we can change to [EntityGrouping.aggregateColumns2] or
- * [EntityGrouping.aggregateColumns3], then we need to wrap our aggregate expressions by [Pair] or [Triple] in
- * the closure, and the function’s return type becomes `Map<K?, Pair<C1?, C2?>>` or `Map<K?, Triple<C1?, C2?, C3?>>`.
+ * Ktorm also supports aggregating two or more columns, we just need to wrap our aggregate expressions by [tupleOf]
+ * in the closure, then the function’s return type becomes `Map<K?, TupleN<C1?, C2?, .. Cn?>>`.
  *
  * @param aggregationSelector a function that accepts the source table and returns the aggregate expression.
  * @return a [Map] associating the key of each group with the result of aggregation of the group elements.
@@ -104,9 +103,8 @@ public inline fun <E : Any, T : BaseTable<E>, K, C> EntityGrouping<E, T, K>.aggr
  * The key for each group is provided by the [EntityGrouping.keySelector] function, and the generated SQL is like:
  * `select key, aggregation from source group by key`.
  *
- * Ktorm also supports aggregating two or more columns, we can change to [EntityGrouping.aggregateColumns2To] or
- * [EntityGrouping.aggregateColumns3To], then we need to wrap our aggregate expressions by [Pair] or [Triple] in
- * the closure, and the function’s return type becomes `Map<K?, Pair<C1?, C2?>>` or `Map<K?, Triple<C1?, C2?, C3?>>`.
+ * Ktorm also supports aggregating two or more columns, we just need to wrap our aggregate expressions by [tupleOf]
+ * in the closure, then the function’s return type becomes `Map<K?, TupleN<C1?, C2?, .. Cn?>>`.
  *
  * @param destination a [MutableMap] used to store the results.
  * @param aggregationSelector a function that accepts the source table and returns the aggregate expression.

ktorm-core/src/main/kotlin/me/liuwj/ktorm/entity/EntitySequence.kt

@@ -497,9 +497,8 @@ public inline fun <E : Any, R, C : MutableCollection<in R>> EntitySequence<E, *>
  * element. Besides, the function’s return type is `ColumnDeclaring<C>`, and we should return a column or expression
  * to customize the `select` clause of the generated SQL.
  *
- * Ktorm also supports selecting two or more columns, we can change to [mapColumns2] or [mapColumns3], then we need
- * to wrap our selected columns by [Pair] or [Triple] in the closure, and the function’s return type becomes
- * `List<Pair<C1?, C2?>>` or `List<Triple<C1?, C2?, C3?>>`.
+ * Ktorm also supports selecting two or more columns, we just need to wrap our selected columns by [tupleOf]
+ * in the closure, then the function’s return type becomes `List<TupleN<C1?, C2?, .. Cn?>>`.
  *
  * The operation is terminal.
  *
@@ -525,9 +524,8 @@ public inline fun <E : Any, T : BaseTable<E>, C : Any> EntitySequence<E, T>.mapC
  * element. Besides, the function’s return type is `ColumnDeclaring<C>`, and we should return a column or expression
  * to customize the `select` clause of the generated SQL.
  *
- * Ktorm also supports selecting two or more columns, we can change to [mapColumns2To] or [mapColumns3To], then we need
- * to wrap our selected columns by [Pair] or [Triple] in the closure, and the function’s return type becomes
- * `List<Pair<C1?, C2?>>` or `List<Triple<C1?, C2?, C3?>>`.
+ * Ktorm also supports selecting two or more columns, we just need to wrap our selected columns by [tupleOf]
+ * in the closure, then the function’s return type becomes `List<TupleN<C1?, C2?, .. Cn?>>`.
  *
  * The operation is terminal.
  *
@@ -671,9 +669,8 @@ public fun <E : Any, T : BaseTable<E>> EntitySequence<E, T>.take(n: Int): Entity
  * Perform an aggregation given by [aggregationSelector] for all elements in the sequence,
  * and return the aggregate result.
  *
- * Ktorm also supports aggregating two or more columns, we can change to [EntitySequence.aggregateColumns2] or
- * [EntitySequence.aggregateColumns3], then we need to wrap our aggregate expressions by [Pair] or [Triple] in
- * the closure, and the function’s return type becomes `Pair<C1?, C2?>` or `Triple<C1?, C2?, C3?>`.
+ * Ktorm also supports aggregating two or more columns, we just need to wrap our aggregate expressions by
+ * [tupleOf] in the closure, then the function’s return type becomes `TupleN<C1?, C2?, .. Cn?>`.
  *
  * The operation is terminal.
  *