Rename `filter` to `mapper`

mirai-core/src/commonMain/kotlin/net.mamoe.mirai/event/linear.kt

@@ -11,42 +11,45 @@ package net.mamoe.mirai.event
 
 import kotlinx.coroutines.*
 import net.mamoe.mirai.utils.MiraiExperimentalAPI
+import net.mamoe.mirai.utils.SinceMirai
 import kotlin.coroutines.CoroutineContext
 import kotlin.coroutines.EmptyCoroutineContext
 
 /**
  * 挂起当前协程, 监听这个事件, 并尝试从这个事件中获取一个值.
  *
- * 若 [filter] 抛出了一个异常, 本函数会立即抛出这个异常.
+ * 若 [mapper] 抛出了一个异常, 本函数会立即抛出这个异常.
  *
  * @param timeoutMillis 超时. 单位为毫秒. `-1` 为不限制
- * @param filter 过滤器. 返回非 null 则代表得到了需要的值. [subscribingGet] 会返回这个值
+ * @param mapper 过滤转换器. 返回非 null 则代表得到了需要的值. [subscribingGet] 会返回这个值
  *
  * @see subscribingGetAsync 本函数的异步版本
  */
+@SinceMirai("0.28.0")
 @MiraiExperimentalAPI
 suspend inline fun <reified E : Event, R : Any> subscribingGet(
     timeoutMillis: Long = -1,
-    noinline filter: E.(E) -> R? // 不要 crossinline: crossinline 后 stacktrace 会不正常
+    noinline mapper: suspend E.(E) -> R? // 不要 crossinline: crossinline 后 stacktrace 会不正常
 ): R {
     require(timeoutMillis == -1L || timeoutMillis > 0) { "timeoutMillis must be -1 or > 0" }
-    return subscribingGetOrNull(timeoutMillis, filter) ?: error("timeout subscribingGet")
+    return subscribingGetOrNull(timeoutMillis, mapper) ?: error("timeout subscribingGet")
 }
 
 /**
  * 挂起当前协程, 监听这个事件, 并尝试从这个事件中获取一个值.
  *
- * 若 [filter] 抛出了一个异常, 本函数会立即抛出这个异常.
+ * 若 [mapper] 抛出了一个异常, 本函数会立即抛出这个异常.
  *
  * @param timeoutMillis 超时. 单位为毫秒. `-1` 为不限制
- * @param filter 过滤器. 返回非 null 则代表得到了需要的值. [subscribingGet] 会返回这个值
+ * @param mapper 过滤转换器. 返回非 null 则代表得到了需要的值. [subscribingGet] 会返回这个值
  *
  * @see subscribingGetAsync 本函数的异步版本
  */
+@SinceMirai("0.28.0")
 @MiraiExperimentalAPI
 suspend inline fun <reified E : Event, R : Any> subscribingGetOrNull(
     timeoutMillis: Long = -1,
-    noinline filter: E.(E) -> R? // 不要 crossinline: crossinline 后 stacktrace 会不正常
+    noinline mapper: suspend E.(E) -> R? // 不要 crossinline: crossinline 后 stacktrace 会不正常
 ): R? {
     require(timeoutMillis == -1L || timeoutMillis > 0) { "timeoutMillis must be -1 or > 0" }
     var result: R? = null
@@ -58,7 +61,7 @@ suspend inline fun <reified E : Event, R : Any> subscribingGetOrNull(
             var listener: Listener<E>? = null
             listener = this.subscribe {
                 val value = try {
-                    filter.invoke(this, it)
+                    mapper.invoke(this, it)
                 } catch (e: Exception) {
                     resultThrowable = e
                     return@subscribe ListeningStatus.STOPPED.also { listener!!.complete() }
@@ -76,7 +79,7 @@ suspend inline fun <reified E : Event, R : Any> subscribingGetOrNull(
             @Suppress("DuplicatedCode") // for better performance
             listener = this.subscribe {
                 val value = try {
-                    filter.invoke(this, it)
+                    mapper.invoke(this, it)
                 } catch (e: Exception) {
                     resultThrowable = e
                     return@subscribe ListeningStatus.STOPPED.also { listener!!.complete() }
@@ -96,17 +99,17 @@ suspend inline fun <reified E : Event, R : Any> subscribingGetOrNull(
 /**
  * 异步监听这个事件, 并尝试从这个事件中获取一个值.
  *
- * 若 [filter] 抛出的异常将会被传递给 [Deferred.await] 抛出.
+ * 若 [mapper] 抛出的异常将会被传递给 [Deferred.await] 抛出.
  *
  * @param timeoutMillis 超时. 单位为毫秒. `-1` 为不限制
  * @param coroutineContext 额外的 [CoroutineContext]
- * @param filter 过滤器. 返回非 null 则代表得到了需要的值. [subscribingGet] 会返回这个值
+ * @param mapper 过滤转换器. 返回非 null 则代表得到了需要的值. [subscribingGet] 会返回这个值
  */
 @MiraiExperimentalAPI
 inline fun <reified E : Event, R : Any> CoroutineScope.subscribingGetAsync(
     coroutineContext: CoroutineContext = EmptyCoroutineContext,
     timeoutMillis: Long = -1,
-    noinline filter: E.(E) -> R? // 不要 crossinline: crossinline 后 stacktrace 会不正常
+    noinline mapper: suspend E.(E) -> R? // 不要 crossinline: crossinline 后 stacktrace 会不正常
 ): Deferred<R> = this.async(coroutineContext) {
-    subscribingGet(timeoutMillis, filter)
+    subscribingGet(timeoutMillis, mapper)
 }
\ No newline at end of file