Merge pull request #153 from InsanusMokrassar/0.14.0

0.14.0

CHANGELOG.md

@@ -1,5 +1,11 @@
 # SauceNaoAPI Changelog
 
+## 0.14.0
+
+* `LimitStatus` is `Comparable<LimitStatus>` since this update
+* `Limits` is `Comparable<Limits>` since this update
+* Main API has been changed
+
 ## 0.13.0
 
 * Versions:

gradle.properties

@@ -1,3 +1,3 @@
 kotlin.code.style=official
 
-library_version=0.13.0
+library_version=0.14.0

gradle/wrapper/gradle-wrapper.properties

@@ -3,4 +3,4 @@ distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-7.5.1-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-7.6-bin.zip

src/commonMain/kotlin/dev/inmo/saucenaoapi/SauceNaoAPI.kt

@@ -22,6 +22,7 @@ private const val URL_FIELD = "url"
 private const val FILE_FIELD = "file"
 private const val FILENAME_FIELD = "filename"
 private const val DB_FIELD = "db"
+private const val DBS_FIELD = "dbs[]"
 private const val DBMASK_FIELD = "dbmask"
 private const val DBMASKI_FIELD = "dbmaski"
 private const val RESULTS_COUNT_FIELD = "numres"
@@ -92,6 +93,45 @@ data class SauceNaoAPI(
         minSimilarity = minSimilarity
     )
 
+    /**
+     * @param db search a specific index number or all without needing to generate a bitmask.
+     * @param dbs search one or more specific index number, set more than once to search multiple.
+     */
+    suspend fun requestByDBs(
+        url: String,
+        db: Int? = null,
+        dbs: Array<Int>? = null,
+        resultsCount: Int? = null,
+        minSimilarity: Float? = null
+    ): SauceNaoAnswer = makeRequest(
+        url.asSauceRequestSubject,
+        db = db,
+        dbs = dbs,
+        resultsCount = resultsCount,
+        minSimilarity = minSimilarity
+    )
+
+    /**
+     * @param mask Mask for selecting specific indexes to ENABLE. dbmask=8191 will search all of the first 14 indexes. If intending to search all databases, the db=999 option is more appropriate.
+     * @param excludedMask Mask for selecting specific indexes to DISABLE. dbmaski=8191 would search only indexes higher than the first 14. This is ideal when attempting to disable only certain indexes, while allowing future indexes to be included by default.
+     *
+     * Bitmask Note: Index numbers start with 0. Even though pixiv is labeled as index 5, it would be controlled with the 6th bit position, which has a decimal value of 32 when set.
+     * db=<index num or 999 for all>
+     */
+    suspend fun requestByMasks(
+        url: String,
+        mask: Int?,
+        excludedMask: Int? = null,
+        resultsCount: Int? = null,
+        minSimilarity: Float? = null
+    ): SauceNaoAnswer = makeRequest(
+        url.asSauceRequestSubject,
+        dbmask = mask,
+        dbmaski = excludedMask,
+        resultsCount = resultsCount,
+        minSimilarity = minSimilarity
+    )
+
     suspend fun request(
         mediaInput: Input,
         mimeType: ContentType,
@@ -103,6 +143,47 @@ data class SauceNaoAPI(
         minSimilarity = minSimilarity
     )
 
+    /**
+     * @param db search a specific index number or all without needing to generate a bitmask.
+     * @param dbs search one or more specific index number, set more than once to search multiple.
+     */
+    suspend fun requestByDBs(
+        mediaInput: Input,
+        mimeType: ContentType,
+        db: Int? = null,
+        dbs: Array<Int>? = null,
+        resultsCount: Int? = null,
+        minSimilarity: Float? = null
+    ): SauceNaoAnswer = makeRequest(
+        mediaInput.asSauceRequestSubject(mimeType),
+        db = db,
+        dbs = dbs,
+        resultsCount = resultsCount,
+        minSimilarity = minSimilarity
+    )
+
+    /**
+     * @param mask Mask for selecting specific indexes to ENABLE. dbmask=8191 will search all of the first 14 indexes. If intending to search all databases, the db=999 option is more appropriate.
+     * @param excludedMask Mask for selecting specific indexes to DISABLE. dbmaski=8191 would search only indexes higher than the first 14. This is ideal when attempting to disable only certain indexes, while allowing future indexes to be included by default.
+     *
+     * Bitmask Note: Index numbers start with 0. Even though pixiv is labeled as index 5, it would be controlled with the 6th bit position, which has a decimal value of 32 when set.
+     * db=<index num or 999 for all>
+     */
+    suspend fun requestByMasks(
+        mediaInput: Input,
+        mimeType: ContentType,
+        mask: Int?,
+        excludedMask: Int? = null,
+        resultsCount: Int? = null,
+        minSimilarity: Float? = null
+    ): SauceNaoAnswer = makeRequest(
+        mediaInput.asSauceRequestSubject(mimeType),
+        dbmask = mask,
+        dbmaski = excludedMask,
+        resultsCount = resultsCount,
+        minSimilarity = minSimilarity
+    )
+
     suspend fun request(
         file: MPPFile,
         resultsCount: Int? = null,
@@ -110,44 +191,91 @@ data class SauceNaoAPI(
     ): SauceNaoAnswer = request(
         file.input,
         file.contentType,
-        resultsCount = resultsCount,
+        resultsCount,
-        minSimilarity = minSimilarity
+        minSimilarity
     )
 
+    /**
+     * @param db search a specific index number or all without needing to generate a bitmask.
+     * @param dbs search one or more specific index number, set more than once to search multiple.
+     */
+    suspend fun requestByDBs(
+        file: MPPFile,
+        db: Int? = null,
+        dbs: Array<Int>? = null,
+        resultsCount: Int? = null,
+        minSimilarity: Float? = null
+    ): SauceNaoAnswer = requestByDBs(
+        file.input,
+        file.contentType,
+        db,
+        dbs,
+        resultsCount,
+        minSimilarity
+    )
+
+    /**
+     * @param mask Mask for selecting specific indexes to ENABLE. dbmask=8191 will search all of the first 14 indexes. If intending to search all databases, the db=999 option is more appropriate.
+     * @param excludedMask Mask for selecting specific indexes to DISABLE. dbmaski=8191 would search only indexes higher than the first 14. This is ideal when attempting to disable only certain indexes, while allowing future indexes to be included by default.
+     *
+     * Bitmask Note: Index numbers start with 0. Even though pixiv is labeled as index 5, it would be controlled with the 6th bit position, which has a decimal value of 32 when set.
+     * db=<index num or 999 for all>
+     */
+    suspend fun requestByMasks(
+        file: MPPFile,
+        mask: Int?,
+        excludedMask: Int? = null,
+        resultsCount: Int? = null,
+        minSimilarity: Float? = null
+    ): SauceNaoAnswer = requestByMasks(
+        file.input,
+        file.contentType,
+        mask,
+        excludedMask,
+        resultsCount,
+        minSimilarity
+    )
+
+    @Deprecated("Renamed", ReplaceWith("requestByDBs(url, db, null, resultsCount, minSimilarity)"))
     suspend fun requestByDb(
         url: String,
         db: Int,
         resultsCount: Int? = null,
         minSimilarity: Float? = null
-    ): SauceNaoAnswer = makeRequest(
+    ): SauceNaoAnswer = requestByDBs(
-        url.asSauceRequestSubject,
+        url,
-        db = db,
+        db,
-        resultsCount = resultsCount,
+        null,
-        minSimilarity = minSimilarity
+        resultsCount,
+        minSimilarity
     )
 
-    suspend fun requestByMask(
+    @Deprecated("Renamed", ReplaceWith("requestByMasks(url, dbmask, null, resultsCount, minSimilarity)"))
+    suspend fun request(
         url: String,
         dbmask: Int,
         resultsCount: Int? = null,
         minSimilarity: Float? = null
-    ): SauceNaoAnswer = makeRequest(
+    ): SauceNaoAnswer = requestByMasks(
-        url.asSauceRequestSubject,
+        url,
-        dbmask = dbmask,
+        dbmask,
-        resultsCount = resultsCount,
+        null,
-        minSimilarity = minSimilarity
+        resultsCount,
+        minSimilarity
     )
 
+    @Deprecated("Renamed", ReplaceWith("requestByMasks(url, null, dbmaski, resultsCount, minSimilarity)"))
     suspend fun requestByMaskI(
         url: String,
         dbmaski: Int,
         resultsCount: Int? = null,
         minSimilarity: Float? = null
-    ): SauceNaoAnswer = makeRequest(
+    ): SauceNaoAnswer = requestByMasks(
-        url.asSauceRequestSubject,
+        url,
-        dbmaski = dbmaski,
+        null,
-        resultsCount = resultsCount,
+        dbmaski,
-        minSimilarity = minSimilarity
+        resultsCount,
+        minSimilarity
     )
 
     private suspend fun makeRequest(
@@ -169,6 +297,7 @@ data class SauceNaoAPI(
     private suspend fun makeRequest(
         request: SauceRequestSubject,
         db: Int? = null,
+        dbs: Array<Int>? = null,
         dbmask: Int? = null,
         dbmaski: Int? = null,
         resultsCount: Int? = null,
@@ -183,6 +312,7 @@ data class SauceNaoAPI(
                 apiToken ?.also { parameter(API_TOKEN_FIELD, it) }
                 parameter(OUTPUT_TYPE_FIELD, JsonOutputType.typeCode)
                 db ?.also { parameter(DB_FIELD, it) }
+                dbs ?.forEach { parameter(DBS_FIELD, it) }
                 dbmask ?.also { parameter(DBMASK_FIELD, it) }
                 dbmaski ?.also { parameter(DBMASKI_FIELD, it) }
                 resultsCount ?.also { parameter(RESULTS_COUNT_FIELD, it) }

src/commonMain/kotlin/dev/inmo/saucenaoapi/additional/header/AccountInfo.kt

@@ -29,15 +29,27 @@ val Header.accountInfo
 data class LimitStatus(
     val remain: Int = Int.MAX_VALUE,
     val limit: Int = Int.MAX_VALUE
-)
+) : Comparable<LimitStatus> {
+    override fun compareTo(other: LimitStatus): Int = when {
+        limit == other.limit && remain == other.remain -> 0
+        else -> remain.compareTo(other.remain)
+    }
+}
 
 data class Limits(
     val short: LimitStatus = LimitStatus(),
     val long: LimitStatus = LimitStatus()
-)
+) : Comparable<Limits> {
+    override fun compareTo(other: Limits): Int = when {
+        long == other.long && short == other.short -> 0
+        else -> short.remain.compareTo(other.short.remain)
+    }
+}
 
 data class AccountInfo(
     val accountType: AccountType = defaultAccountType,
     val userId: UserId? = null,
     val limits: Limits = Limits()
-)
+) : Comparable<AccountInfo> {
+    override fun compareTo(other: AccountInfo): Int = limits.compareTo(other.limits)
+}

src/commonMain/kotlin/dev/inmo/saucenaoapi/models/LimitsState.kt

@@ -8,4 +8,6 @@ data class LimitsState(
     val maxLongQuota: Int,
     val knownShortQuota: Int,
     val knownLongQuota: Int
-)
+) : Comparable<LimitsState> {
+    override fun compareTo(other: LimitsState): Int = knownShortQuota.compareTo(other.knownShortQuota)
+}