lpw
2024-06-12 09e73ac42fe2feb7925d954fed88a2eaa57697f7
commit | author | age
6e1425 1 #import <Foundation/Foundation.h>
H 2
09e73a 3 NS_ASSUME_NONNULL_BEGIN
L 4
6e1425 5 #ifndef __has_feature      // Optional.
H 6 #define __has_feature(x) 0 // Compatibility with non-clang compilers.
7 #endif
8
9 #ifndef NS_RETURNS_NOT_RETAINED
10 #if __has_feature(attribute_ns_returns_not_retained)
11 #define NS_RETURNS_NOT_RETAINED __attribute__((ns_returns_not_retained))
12 #else
13 #define NS_RETURNS_NOT_RETAINED
14 #endif
15 #endif
16
17 @class FMDatabase;
18 @class FMStatement;
19
09e73a 20 /** Types for columns in a result set.
L 21  */
22 typedef NS_ENUM(int, SqliteValueType) {
23     SqliteValueTypeInteger = 1,
24     SqliteValueTypeFloat   = 2,
25     SqliteValueTypeText    = 3,
26     SqliteValueTypeBlob    = 4,
27     SqliteValueTypeNull    = 5
28 };
29
30 /** Represents the results of executing a query on an @c FMDatabase .
6e1425 31  
09e73a 32  See also
6e1425 33  
09e73a 34  - @c FMDatabase 
6e1425 35  */
H 36
09e73a 37 @interface FMResultSet : NSObject
L 38
39 @property (nonatomic, retain, nullable) FMDatabase *parentDB;
6e1425 40
H 41 ///-----------------
42 /// @name Properties
43 ///-----------------
44
45 /** Executed query */
46
09e73a 47 @property (atomic, retain, nullable) NSString *query;
6e1425 48
H 49 /** `NSMutableDictionary` mapping column names to numeric index */
50
51 @property (readonly) NSMutableDictionary *columnNameToIndexMap;
52
53 /** `FMStatement` used by result set. */
54
09e73a 55 @property (atomic, retain, nullable) FMStatement *statement;
6e1425 56
H 57 ///------------------------------------
09e73a 58 /// @name Creating and closing a result set
6e1425 59 ///------------------------------------
H 60
61 /** Close result set */
62
63 - (void)close;
64
65 ///---------------------------------------
66 /// @name Iterating through the result set
67 ///---------------------------------------
68
69 /** Retrieve next row for result set.
70  
71  You must always invoke `next` or `nextWithError` before attempting to access the values returned in a query, even if you're only expecting one.
72
09e73a 73  @return @c YES if row successfully retrieved; @c NO if end of result set reached
6e1425 74  
H 75  @see hasAnotherRow
76  */
77
78 - (BOOL)next;
79
80 /** Retrieve next row for result set.
81  
82   You must always invoke `next` or `nextWithError` before attempting to access the values returned in a query, even if you're only expecting one.
83  
84  @param outErr A 'NSError' object to receive any error object (if any).
85  
86  @return 'YES' if row successfully retrieved; 'NO' if end of result set reached
87  
88  @see hasAnotherRow
89  */
90
09e73a 91 - (BOOL)nextWithError:(NSError * _Nullable __autoreleasing *)outErr;
L 92
93 /** Perform SQL statement.
94
95  @return 'YES' if successful; 'NO' if not.
96
97  @see hasAnotherRow
98 */
99
100 - (BOOL)step;
101
102 /** Perform SQL statement.
103
104  @param outErr A 'NSError' object to receive any error object (if any).
105
106  @return 'YES' if successful; 'NO' if not.
107
108  @see hasAnotherRow
109 */
110
111 - (BOOL)stepWithError:(NSError * _Nullable __autoreleasing *)outErr;
6e1425 112
H 113 /** Did the last call to `<next>` succeed in retrieving another row?
114
09e73a 115  @return 'YES' if there is another row; 'NO' if not.
L 116
6e1425 117  @see next
H 118  
09e73a 119  @warning The `hasAnotherRow` method must follow a call to `<next>`. If the previous database interaction was something other than a call to `next`, then this method may return @c NO, whether there is another row of data or not.
6e1425 120  */
H 121
122 - (BOOL)hasAnotherRow;
123
124 ///---------------------------------------------
125 /// @name Retrieving information from result set
126 ///---------------------------------------------
127
128 /** How many columns in result set
129  
130  @return Integer value of the number of columns.
131  */
132
09e73a 133 @property (nonatomic, readonly) int columnCount;
6e1425 134
H 135 /** Column index for column name
136
09e73a 137  @param columnName @c NSString  value of the name of the column.
6e1425 138
H 139  @return Zero-based index for column.
140  */
141
142 - (int)columnIndexForName:(NSString*)columnName;
143
144 /** Column name for column index
145
146  @param columnIdx Zero-based index for column.
147
09e73a 148  @return columnName @c NSString  value of the name of the column.
6e1425 149  */
H 150
09e73a 151 - (NSString * _Nullable)columnNameForIndex:(int)columnIdx;
6e1425 152
H 153 /** Result set integer value for column.
154
09e73a 155  @param columnName @c NSString  value of the name of the column.
6e1425 156
09e73a 157  @return @c int  value of the result set's column.
6e1425 158  */
H 159
160 - (int)intForColumn:(NSString*)columnName;
161
162 /** Result set integer value for column.
163
164  @param columnIdx Zero-based index for column.
165
09e73a 166  @return @c int  value of the result set's column.
6e1425 167  */
H 168
169 - (int)intForColumnIndex:(int)columnIdx;
170
09e73a 171 /** Result set @c long  value for column.
6e1425 172
09e73a 173  @param columnName @c NSString  value of the name of the column.
6e1425 174
09e73a 175  @return @c long  value of the result set's column.
6e1425 176  */
H 177
178 - (long)longForColumn:(NSString*)columnName;
179
180 /** Result set long value for column.
181
182  @param columnIdx Zero-based index for column.
183
09e73a 184  @return @c long  value of the result set's column.
6e1425 185  */
H 186
187 - (long)longForColumnIndex:(int)columnIdx;
188
189 /** Result set `long long int` value for column.
190
09e73a 191  @param columnName @c NSString  value of the name of the column.
6e1425 192
H 193  @return `long long int` value of the result set's column.
194  */
195
196 - (long long int)longLongIntForColumn:(NSString*)columnName;
197
198 /** Result set `long long int` value for column.
199
200  @param columnIdx Zero-based index for column.
201
202  @return `long long int` value of the result set's column.
203  */
204
205 - (long long int)longLongIntForColumnIndex:(int)columnIdx;
206
207 /** Result set `unsigned long long int` value for column.
208
09e73a 209  @param columnName @c NSString  value of the name of the column.
6e1425 210
H 211  @return `unsigned long long int` value of the result set's column.
212  */
213
214 - (unsigned long long int)unsignedLongLongIntForColumn:(NSString*)columnName;
215
216 /** Result set `unsigned long long int` value for column.
217
218  @param columnIdx Zero-based index for column.
219
220  @return `unsigned long long int` value of the result set's column.
221  */
222
223 - (unsigned long long int)unsignedLongLongIntForColumnIndex:(int)columnIdx;
224
225 /** Result set `BOOL` value for column.
226
09e73a 227  @param columnName @c NSString  value of the name of the column.
6e1425 228
H 229  @return `BOOL` value of the result set's column.
230  */
231
232 - (BOOL)boolForColumn:(NSString*)columnName;
233
234 /** Result set `BOOL` value for column.
235
236  @param columnIdx Zero-based index for column.
237
238  @return `BOOL` value of the result set's column.
239  */
240
241 - (BOOL)boolForColumnIndex:(int)columnIdx;
242
243 /** Result set `double` value for column.
244
09e73a 245  @param columnName @c NSString  value of the name of the column.
6e1425 246
H 247  @return `double` value of the result set's column.
248  
249  */
250
251 - (double)doubleForColumn:(NSString*)columnName;
252
253 /** Result set `double` value for column.
254
255  @param columnIdx Zero-based index for column.
256
257  @return `double` value of the result set's column.
258  
259  */
260
261 - (double)doubleForColumnIndex:(int)columnIdx;
262
09e73a 263 /** Result set @c NSString  value for column.
6e1425 264
09e73a 265  @param columnName @c NSString  value of the name of the column.
6e1425 266
09e73a 267  @return String value of the result set's column.
6e1425 268  
H 269  */
270
09e73a 271 - (NSString * _Nullable)stringForColumn:(NSString*)columnName;
6e1425 272
09e73a 273 /** Result set @c NSString  value for column.
6e1425 274
H 275  @param columnIdx Zero-based index for column.
276
09e73a 277  @return String value of the result set's column.
6e1425 278  */
H 279
09e73a 280 - (NSString * _Nullable)stringForColumnIndex:(int)columnIdx;
6e1425 281
09e73a 282 /** Result set @c NSDate  value for column.
6e1425 283
09e73a 284  @param columnName @c NSString  value of the name of the column.
6e1425 285
09e73a 286  @return Date value of the result set's column.
6e1425 287  */
H 288
09e73a 289 - (NSDate * _Nullable)dateForColumn:(NSString*)columnName;
6e1425 290
09e73a 291 /** Result set @c NSDate  value for column.
6e1425 292
H 293  @param columnIdx Zero-based index for column.
294
09e73a 295  @return Date value of the result set's column.
6e1425 296  
H 297  */
298
09e73a 299 - (NSDate * _Nullable)dateForColumnIndex:(int)columnIdx;
6e1425 300
09e73a 301 /** Result set @c NSData  value for column.
6e1425 302  
H 303  This is useful when storing binary data in table (such as image or the like).
304
09e73a 305  @param columnName @c NSString  value of the name of the column.
6e1425 306
09e73a 307  @return Data value of the result set's column.
6e1425 308  
H 309  */
310
09e73a 311 - (NSData * _Nullable)dataForColumn:(NSString*)columnName;
6e1425 312
09e73a 313 /** Result set @c NSData  value for column.
6e1425 314
H 315  @param columnIdx Zero-based index for column.
316
09e73a 317  @warning For zero length BLOBs, this will return `nil`. Use `typeForColumn` to determine whether this was really a zero
L 318     length BLOB or `NULL`.
319
320  @return Data value of the result set's column.
6e1425 321  */
H 322
09e73a 323 - (NSData * _Nullable)dataForColumnIndex:(int)columnIdx;
6e1425 324
H 325 /** Result set `(const unsigned char *)` value for column.
326
09e73a 327  @param columnName @c NSString  value of the name of the column.
L 328
329  @warning For zero length BLOBs, this will return `nil`. Use `typeForColumnIndex` to determine whether this was really a zero
330  length BLOB or `NULL`.
6e1425 331
H 332  @return `(const unsigned char *)` value of the result set's column.
333  */
334
09e73a 335 - (const unsigned char * _Nullable)UTF8StringForColumn:(NSString*)columnName;
L 336
337 - (const unsigned char * _Nullable)UTF8StringForColumnName:(NSString*)columnName __deprecated_msg("Use UTF8StringForColumn instead");
6e1425 338
H 339 /** Result set `(const unsigned char *)` value for column.
340
341  @param columnIdx Zero-based index for column.
342
343  @return `(const unsigned char *)` value of the result set's column.
344  */
345
09e73a 346 - (const unsigned char * _Nullable)UTF8StringForColumnIndex:(int)columnIdx;
6e1425 347
H 348 /** Result set object for column.
349
09e73a 350  @param columnName Name of the column.
6e1425 351
09e73a 352  @return Either @c NSNumber , @c NSString , @c NSData , or @c NSNull . If the column was @c NULL , this returns `[NSNull null]` object.
6e1425 353
H 354  @see objectForKeyedSubscript:
355  */
356
09e73a 357 - (id _Nullable)objectForColumn:(NSString*)columnName;
L 358
359 - (id _Nullable)objectForColumnName:(NSString*)columnName __deprecated_msg("Use objectForColumn instead");
360
361 /** Column type by column name.
362
363  @param columnName Name of the column.
364
365  @return The `SqliteValueType` of the value in this column.
366  */
367
368 - (SqliteValueType)typeForColumn:(NSString*)columnName;
369
370 /** Column type by column index.
371
372  @param columnIdx Index of the column.
373
374  @return The `SqliteValueType` of the value in this column.
375  */
376
377 - (SqliteValueType)typeForColumnIndex:(int)columnIdx;
378
6e1425 379
H 380 /** Result set object for column.
381
382  @param columnIdx Zero-based index for column.
383
09e73a 384  @return Either @c NSNumber , @c NSString , @c NSData , or @c NSNull . If the column was @c NULL , this returns `[NSNull null]` object.
6e1425 385
H 386  @see objectAtIndexedSubscript:
387  */
388
09e73a 389 - (id _Nullable)objectForColumnIndex:(int)columnIdx;
6e1425 390
H 391 /** Result set object for column.
392  
393  This method allows the use of the "boxed" syntax supported in Modern Objective-C. For example, by defining this method, the following syntax is now supported:
09e73a 394
L 395 @code
396 id result = rs[@"employee_name"];
397 @endcode
398
6e1425 399  This simplified syntax is equivalent to calling:
H 400  
09e73a 401 @code
L 402 id result = [rs objectForKeyedSubscript:@"employee_name"];
403 @endcode
404
6e1425 405  which is, it turns out, equivalent to calling:
H 406  
09e73a 407 @code
L 408 id result = [rs objectForColumnName:@"employee_name"];
409 @endcode
6e1425 410
09e73a 411  @param columnName @c NSString  value of the name of the column.
6e1425 412
09e73a 413  @return Either @c NSNumber , @c NSString , @c NSData , or @c NSNull . If the column was @c NULL , this returns `[NSNull null]` object.
6e1425 414  */
H 415
09e73a 416 - (id _Nullable)objectForKeyedSubscript:(NSString *)columnName;
6e1425 417
H 418 /** Result set object for column.
419
420  This method allows the use of the "boxed" syntax supported in Modern Objective-C. For example, by defining this method, the following syntax is now supported:
421
09e73a 422 @code
L 423 id result = rs[0];
424 @endcode
6e1425 425
H 426  This simplified syntax is equivalent to calling:
427
09e73a 428 @code
L 429 id result = [rs objectForKeyedSubscript:0];
430 @endcode
6e1425 431
H 432  which is, it turns out, equivalent to calling:
433
09e73a 434 @code
L 435 id result = [rs objectForColumnName:0];
436 @endcode
6e1425 437
H 438  @param columnIdx Zero-based index for column.
439
09e73a 440  @return Either @c NSNumber , @c NSString , @c NSData , or @c NSNull . If the column was @c NULL , this returns `[NSNull null]` object.
6e1425 441  */
H 442
09e73a 443 - (id _Nullable)objectAtIndexedSubscript:(int)columnIdx;
6e1425 444
09e73a 445 /** Result set @c NSData  value for column.
6e1425 446
09e73a 447  @param columnName @c NSString  value of the name of the column.
6e1425 448
09e73a 449  @return Data value of the result set's column.
6e1425 450
H 451  @warning If you are going to use this data after you iterate over the next row, or after you close the
452 result set, make sure to make a copy of the data first (or just use `<dataForColumn:>`/`<dataForColumnIndex:>`)
453 If you don't, you're going to be in a world of hurt when you try and use the data.
454  
455  */
456
09e73a 457 - (NSData * _Nullable)dataNoCopyForColumn:(NSString *)columnName NS_RETURNS_NOT_RETAINED;
6e1425 458
09e73a 459 /** Result set @c NSData  value for column.
6e1425 460
H 461  @param columnIdx Zero-based index for column.
462
09e73a 463  @return Data value of the result set's column.
6e1425 464
H 465  @warning If you are going to use this data after you iterate over the next row, or after you close the
466  result set, make sure to make a copy of the data first (or just use `<dataForColumn:>`/`<dataForColumnIndex:>`)
467  If you don't, you're going to be in a world of hurt when you try and use the data.
468
469  */
470
09e73a 471 - (NSData * _Nullable)dataNoCopyForColumnIndex:(int)columnIdx NS_RETURNS_NOT_RETAINED;
6e1425 472
09e73a 473 /** Is the column @c NULL ?
6e1425 474  
H 475  @param columnIdx Zero-based index for column.
476
09e73a 477  @return @c YES if column is @c NULL ; @c NO if not @c NULL .
6e1425 478  */
H 479
480 - (BOOL)columnIndexIsNull:(int)columnIdx;
481
09e73a 482 /** Is the column @c NULL ?
6e1425 483
09e73a 484  @param columnName @c NSString  value of the name of the column.
6e1425 485
09e73a 486  @return @c YES if column is @c NULL ; @c NO if not @c NULL .
6e1425 487  */
H 488
489 - (BOOL)columnIsNull:(NSString*)columnName;
490
491
492 /** Returns a dictionary of the row results mapped to case sensitive keys of the column names. 
493  
494  @warning The keys to the dictionary are case sensitive of the column names.
495  */
496
09e73a 497 @property (nonatomic, readonly, nullable) NSDictionary *resultDictionary;
6e1425 498  
H 499 /** Returns a dictionary of the row results
500  
501  @see resultDictionary
502  
503  @warning **Deprecated**: Please use `<resultDictionary>` instead.  Also, beware that `<resultDictionary>` is case sensitive! 
504  */
505
09e73a 506 - (NSDictionary * _Nullable)resultDict __deprecated_msg("Use resultDictionary instead");
6e1425 507
H 508 ///-----------------------------
509 /// @name Key value coding magic
510 ///-----------------------------
511
512 /** Performs `setValue` to yield support for key value observing.
513  
514  @param object The object for which the values will be set. This is the key-value-coding compliant object that you might, for example, observe.
515
516  */
517
518 - (void)kvcMagic:(id)object;
519
09e73a 520 ///-----------------------------
L 521 /// @name Binding values
522 ///-----------------------------
523
524 /// Bind array of values to prepared statement.
525 ///
526 /// @param array Array of values to bind to SQL statement.
527
528 - (BOOL)bindWithArray:(NSArray*)array;
529
530 /// Bind dictionary of values to prepared statement.
531 ///
532 /// @param dictionary Dictionary of values to bind to SQL statement.
533
534 - (BOOL)bindWithDictionary:(NSDictionary *)dictionary;
535
6e1425 536 @end
H 537
09e73a 538 NS_ASSUME_NONNULL_END