1 /* <lambda>null2 * Copyright 2023 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package androidx.sqlite 18 19 import androidx.annotation.IntRange 20 21 /** 22 * SQLite statement definition. 23 * 24 * A prepared statement is a resource that must be released once it is no longer needed via its 25 * [close] function. 26 * 27 * See also [Prepared Statement](https://www.sqlite.org/c3ref/stmt.html) 28 */ 29 @Suppress("NotCloseable") 30 public interface SQLiteStatement : AutoCloseable { 31 /** 32 * Binds a ByteArray value to this statement at an index. 33 * 34 * @param index the 1-based index of the parameter to bind 35 * @param value the value to bind 36 */ 37 public fun bindBlob(@IntRange(from = 1) index: Int, value: ByteArray) 38 39 /** 40 * Binds a Double value to this statement at an index. 41 * 42 * @param index the 1-based index of the parameter to bind 43 * @param value the value to bind 44 */ 45 public fun bindDouble(@IntRange(from = 1) index: Int, value: Double) 46 47 /** 48 * Binds a Float value to this statement at an index. 49 * 50 * @param index the 1-based index of the parameter to bind 51 * @param value the value to bind 52 */ 53 public fun bindFloat(@IntRange(from = 1) index: Int, value: Float) { 54 bindDouble(index, value.toDouble()) 55 } 56 57 /** 58 * Binds a Long value to this statement at an index. 59 * 60 * @param index the 1-based index of the parameter to bind 61 * @param value the value to bind 62 */ 63 public fun bindLong(@IntRange(from = 1) index: Int, value: Long) 64 65 /** 66 * Binds a Int value to this statement at an index. 67 * 68 * @param index the 1-based index of the parameter to bind 69 * @param value the value to bind 70 */ 71 public fun bindInt(@IntRange(from = 1) index: Int, value: Int) { 72 bindLong(index, value.toLong()) 73 } 74 75 /** 76 * Binds a Boolean value to this statement at an index. 77 * 78 * @param index the 1-based index of the parameter to bind 79 * @param value the value to bind 80 */ 81 public fun bindBoolean(@IntRange(from = 1) index: Int, value: Boolean) { 82 bindLong(index, if (value) 1L else 0L) 83 } 84 85 /** 86 * Binds a String value to this statement at an index. 87 * 88 * @param index the 1-based index of the parameter to bind 89 * @param value the value to bind 90 */ 91 public fun bindText(@IntRange(from = 1) index: Int, value: String) 92 93 /** 94 * Binds a NULL value to this statement at an index. 95 * 96 * @param index the 1-based index of the parameter to bind 97 */ 98 public fun bindNull(@IntRange(from = 1) index: Int) 99 100 /** 101 * Returns the value of the column at [index] as a ByteArray. 102 * 103 * @param index the 0-based index of the column 104 * @return the value of the column 105 */ 106 public fun getBlob(@IntRange(from = 0) index: Int): ByteArray 107 108 /** 109 * Returns the value of the column at [index] as a Double. 110 * 111 * @param index the 0-based index of the column 112 * @return the value of the column 113 */ 114 public fun getDouble(@IntRange(from = 0) index: Int): Double 115 116 /** 117 * Returns the value of the column at [index] as a Float. 118 * 119 * @param index the 0-based index of the column 120 * @return the value of the column 121 */ 122 public fun getFloat(@IntRange(from = 0) index: Int): Float { 123 return getDouble(index).toFloat() 124 } 125 126 /** 127 * Returns the value of the column at [index] as a Long. 128 * 129 * @param index the 0-based index of the column 130 * @return the value of the column 131 */ 132 public fun getLong(@IntRange(from = 0) index: Int): Long 133 134 /** 135 * Returns the value of the column at [index] as a Int. 136 * 137 * @param index the 0-based index of the column 138 * @return the value of the column 139 */ 140 public fun getInt(@IntRange(from = 0) index: Int): Int { 141 return getLong(index).toInt() 142 } 143 144 /** 145 * Returns the value of the column at [index] as a Boolean. 146 * 147 * @param index the 0-based index of the column 148 * @return the value of the column 149 */ 150 public fun getBoolean(@IntRange(from = 0) index: Int): Boolean { 151 return getLong(index) != 0L 152 } 153 154 /** 155 * Returns the value of the column at [index] as a String. 156 * 157 * @param index the 0-based index of the column 158 * @return the value of the column 159 */ 160 public fun getText(@IntRange(from = 0) index: Int): String 161 162 /** 163 * Returns true if the value of the column at [index] is NULL. 164 * 165 * @param index the 0-based index of the column 166 * @return true if the column value is NULL, false otherwise 167 */ 168 public fun isNull(@IntRange(from = 0) index: Int): Boolean 169 170 /** 171 * Returns the number of columns in the result of the statement. 172 * 173 * @return the number of columns 174 */ 175 public fun getColumnCount(): Int 176 177 /** 178 * Returns the name of a column at [index] in the result of the statement. 179 * 180 * @param index the 0-based index of the column 181 * @return the name of the column 182 */ 183 public fun getColumnName(@IntRange(from = 0) index: Int): String 184 185 /** 186 * Returns the name of the columns in the result of the statement ordered by their index. 187 * 188 * @return the names of the columns 189 */ 190 public fun getColumnNames(): List<String> { 191 return List(getColumnCount()) { i -> getColumnName(i) } 192 } 193 194 /** 195 * Returns the data type of a column at [index] in the result of the statement. 196 * 197 * The data type can be used to determine the preferred `get*()` function to be used for the 198 * column but other getters may perform data type conversion. 199 * 200 * @param index the 0-based index of the column 201 * @return the data type of the column 202 */ 203 @DataType public fun getColumnType(@IntRange(from = 0) index: Int): Int 204 205 /** 206 * Executes the statement and evaluates the next result row if available. 207 * 208 * A statement is initially prepared and compiled but is not executed until one or more calls to 209 * this function. If the statement execution produces result rows then this function will return 210 * `true` indicating there is a new row of data ready to be read. 211 * 212 * @return true if there are more rows to evaluate or false if the statement is done executing 213 */ 214 public fun step(): Boolean 215 216 /** 217 * Resets the prepared statement back to initial state so that it can be re-executed via [step]. 218 * Any parameter bound via the `bind*()` APIs will retain their value. 219 */ 220 public fun reset() 221 222 /** Clears all parameter bindings. Unset bindings are treated as NULL. */ 223 public fun clearBindings() 224 225 /** 226 * Closes the statement. 227 * 228 * Once a statement is closed it should no longer be used. Calling this function on an already 229 * closed statement is a no-op. 230 */ 231 public override fun close() 232 } 233