Sin descripción

AWSFMResultSet.h 12KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468
  1. #import <Foundation/Foundation.h>
  2. #ifndef __has_feature // Optional.
  3. #define __has_feature(x) 0 // Compatibility with non-clang compilers.
  4. #endif
  5. #ifndef NS_RETURNS_NOT_RETAINED
  6. #if __has_feature(attribute_ns_returns_not_retained)
  7. #define NS_RETURNS_NOT_RETAINED __attribute__((ns_returns_not_retained))
  8. #else
  9. #define NS_RETURNS_NOT_RETAINED
  10. #endif
  11. #endif
  12. @class AWSFMDatabase;
  13. @class AWSFMStatement;
  14. /** Represents the results of executing a query on an `<FMDatabase>`.
  15. ### See also
  16. - `<FMDatabase>`
  17. */
  18. @interface AWSFMResultSet : NSObject {
  19. AWSFMDatabase *_parentDB;
  20. AWSFMStatement *_statement;
  21. NSString *_query;
  22. NSMutableDictionary *_columnNameToIndexMap;
  23. }
  24. ///-----------------
  25. /// @name Properties
  26. ///-----------------
  27. /** Executed query */
  28. @property (atomic, retain) NSString *query;
  29. /** `NSMutableDictionary` mapping column names to numeric index */
  30. @property (readonly) NSMutableDictionary *columnNameToIndexMap;
  31. /** `FMStatement` used by result set. */
  32. @property (atomic, retain) AWSFMStatement *statement;
  33. ///------------------------------------
  34. /// @name Creating and closing database
  35. ///------------------------------------
  36. /** Create result set from `<FMStatement>`
  37. @param statement A `<FMStatement>` to be performed
  38. @param aDB A `<FMDatabase>` to be used
  39. @return A `FMResultSet` on success; `nil` on failure
  40. */
  41. + (instancetype)resultSetWithStatement:(AWSFMStatement *)statement usingParentDatabase:(AWSFMDatabase*)aDB;
  42. /** Close result set */
  43. - (void)close;
  44. - (void)setParentDB:(AWSFMDatabase *)newDb;
  45. ///---------------------------------------
  46. /// @name Iterating through the result set
  47. ///---------------------------------------
  48. /** Retrieve next row for result set.
  49. You must always invoke `next` or `nextWithError` before attempting to access the values returned in a query, even if you're only expecting one.
  50. @return `YES` if row successfully retrieved; `NO` if end of result set reached
  51. @see hasAnotherRow
  52. */
  53. - (BOOL)next;
  54. /** Retrieve next row for result set.
  55. You must always invoke `next` or `nextWithError` before attempting to access the values returned in a query, even if you're only expecting one.
  56. @param outErr A 'NSError' object to receive any error object (if any).
  57. @return 'YES' if row successfully retrieved; 'NO' if end of result set reached
  58. @see hasAnotherRow
  59. */
  60. - (BOOL)nextWithError:(NSError **)outErr;
  61. /** Did the last call to `<next>` succeed in retrieving another row?
  62. @return `YES` if the last call to `<next>` succeeded in retrieving another record; `NO` if not.
  63. @see next
  64. @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 `NO`, whether there is another row of data or not.
  65. */
  66. - (BOOL)hasAnotherRow;
  67. ///---------------------------------------------
  68. /// @name Retrieving information from result set
  69. ///---------------------------------------------
  70. /** How many columns in result set
  71. @return Integer value of the number of columns.
  72. */
  73. - (int)columnCount;
  74. /** Column index for column name
  75. @param columnName `NSString` value of the name of the column.
  76. @return Zero-based index for column.
  77. */
  78. - (int)columnIndexForName:(NSString*)columnName;
  79. /** Column name for column index
  80. @param columnIdx Zero-based index for column.
  81. @return columnName `NSString` value of the name of the column.
  82. */
  83. - (NSString*)columnNameForIndex:(int)columnIdx;
  84. /** Result set integer value for column.
  85. @param columnName `NSString` value of the name of the column.
  86. @return `int` value of the result set's column.
  87. */
  88. - (int)intForColumn:(NSString*)columnName;
  89. /** Result set integer value for column.
  90. @param columnIdx Zero-based index for column.
  91. @return `int` value of the result set's column.
  92. */
  93. - (int)intForColumnIndex:(int)columnIdx;
  94. /** Result set `long` value for column.
  95. @param columnName `NSString` value of the name of the column.
  96. @return `long` value of the result set's column.
  97. */
  98. - (long)longForColumn:(NSString*)columnName;
  99. /** Result set long value for column.
  100. @param columnIdx Zero-based index for column.
  101. @return `long` value of the result set's column.
  102. */
  103. - (long)longForColumnIndex:(int)columnIdx;
  104. /** Result set `long long int` value for column.
  105. @param columnName `NSString` value of the name of the column.
  106. @return `long long int` value of the result set's column.
  107. */
  108. - (long long int)longLongIntForColumn:(NSString*)columnName;
  109. /** Result set `long long int` value for column.
  110. @param columnIdx Zero-based index for column.
  111. @return `long long int` value of the result set's column.
  112. */
  113. - (long long int)longLongIntForColumnIndex:(int)columnIdx;
  114. /** Result set `unsigned long long int` value for column.
  115. @param columnName `NSString` value of the name of the column.
  116. @return `unsigned long long int` value of the result set's column.
  117. */
  118. - (unsigned long long int)unsignedLongLongIntForColumn:(NSString*)columnName;
  119. /** Result set `unsigned long long int` value for column.
  120. @param columnIdx Zero-based index for column.
  121. @return `unsigned long long int` value of the result set's column.
  122. */
  123. - (unsigned long long int)unsignedLongLongIntForColumnIndex:(int)columnIdx;
  124. /** Result set `BOOL` value for column.
  125. @param columnName `NSString` value of the name of the column.
  126. @return `BOOL` value of the result set's column.
  127. */
  128. - (BOOL)boolForColumn:(NSString*)columnName;
  129. /** Result set `BOOL` value for column.
  130. @param columnIdx Zero-based index for column.
  131. @return `BOOL` value of the result set's column.
  132. */
  133. - (BOOL)boolForColumnIndex:(int)columnIdx;
  134. /** Result set `double` value for column.
  135. @param columnName `NSString` value of the name of the column.
  136. @return `double` value of the result set's column.
  137. */
  138. - (double)doubleForColumn:(NSString*)columnName;
  139. /** Result set `double` value for column.
  140. @param columnIdx Zero-based index for column.
  141. @return `double` value of the result set's column.
  142. */
  143. - (double)doubleForColumnIndex:(int)columnIdx;
  144. /** Result set `NSString` value for column.
  145. @param columnName `NSString` value of the name of the column.
  146. @return `NSString` value of the result set's column.
  147. */
  148. - (NSString*)stringForColumn:(NSString*)columnName;
  149. /** Result set `NSString` value for column.
  150. @param columnIdx Zero-based index for column.
  151. @return `NSString` value of the result set's column.
  152. */
  153. - (NSString*)stringForColumnIndex:(int)columnIdx;
  154. /** Result set `NSDate` value for column.
  155. @param columnName `NSString` value of the name of the column.
  156. @return `NSDate` value of the result set's column.
  157. */
  158. - (NSDate*)dateForColumn:(NSString*)columnName;
  159. /** Result set `NSDate` value for column.
  160. @param columnIdx Zero-based index for column.
  161. @return `NSDate` value of the result set's column.
  162. */
  163. - (NSDate*)dateForColumnIndex:(int)columnIdx;
  164. /** Result set `NSData` value for column.
  165. This is useful when storing binary data in table (such as image or the like).
  166. @param columnName `NSString` value of the name of the column.
  167. @return `NSData` value of the result set's column.
  168. */
  169. - (NSData*)dataForColumn:(NSString*)columnName;
  170. /** Result set `NSData` value for column.
  171. @param columnIdx Zero-based index for column.
  172. @return `NSData` value of the result set's column.
  173. */
  174. - (NSData*)dataForColumnIndex:(int)columnIdx;
  175. /** Result set `(const unsigned char *)` value for column.
  176. @param columnName `NSString` value of the name of the column.
  177. @return `(const unsigned char *)` value of the result set's column.
  178. */
  179. - (const unsigned char *)UTF8StringForColumnName:(NSString*)columnName;
  180. /** Result set `(const unsigned char *)` value for column.
  181. @param columnIdx Zero-based index for column.
  182. @return `(const unsigned char *)` value of the result set's column.
  183. */
  184. - (const unsigned char *)UTF8StringForColumnIndex:(int)columnIdx;
  185. /** Result set object for column.
  186. @param columnName `NSString` value of the name of the column.
  187. @return Either `NSNumber`, `NSString`, `NSData`, or `NSNull`. If the column was `NULL`, this returns `[NSNull null]` object.
  188. @see objectForKeyedSubscript:
  189. */
  190. - (id)objectForColumnName:(NSString*)columnName;
  191. /** Result set object for column.
  192. @param columnIdx Zero-based index for column.
  193. @return Either `NSNumber`, `NSString`, `NSData`, or `NSNull`. If the column was `NULL`, this returns `[NSNull null]` object.
  194. @see objectAtIndexedSubscript:
  195. */
  196. - (id)objectForColumnIndex:(int)columnIdx;
  197. /** Result set object for column.
  198. 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:
  199. id result = rs[@"employee_name"];
  200. This simplified syntax is equivalent to calling:
  201. id result = [rs objectForKeyedSubscript:@"employee_name"];
  202. which is, it turns out, equivalent to calling:
  203. id result = [rs objectForColumnName:@"employee_name"];
  204. @param columnName `NSString` value of the name of the column.
  205. @return Either `NSNumber`, `NSString`, `NSData`, or `NSNull`. If the column was `NULL`, this returns `[NSNull null]` object.
  206. */
  207. - (id)objectForKeyedSubscript:(NSString *)columnName;
  208. /** Result set object for column.
  209. 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:
  210. id result = rs[0];
  211. This simplified syntax is equivalent to calling:
  212. id result = [rs objectForKeyedSubscript:0];
  213. which is, it turns out, equivalent to calling:
  214. id result = [rs objectForColumnName:0];
  215. @param columnIdx Zero-based index for column.
  216. @return Either `NSNumber`, `NSString`, `NSData`, or `NSNull`. If the column was `NULL`, this returns `[NSNull null]` object.
  217. */
  218. - (id)objectAtIndexedSubscript:(int)columnIdx;
  219. /** Result set `NSData` value for column.
  220. @param columnName `NSString` value of the name of the column.
  221. @return `NSData` value of the result set's column.
  222. @warning If you are going to use this data after you iterate over the next row, or after you close the
  223. result set, make sure to make a copy of the data first (or just use `<dataForColumn:>`/`<dataForColumnIndex:>`)
  224. If you don't, you're going to be in a world of hurt when you try and use the data.
  225. */
  226. - (NSData*)dataNoCopyForColumn:(NSString*)columnName NS_RETURNS_NOT_RETAINED;
  227. /** Result set `NSData` value for column.
  228. @param columnIdx Zero-based index for column.
  229. @return `NSData` value of the result set's column.
  230. @warning If you are going to use this data after you iterate over the next row, or after you close the
  231. result set, make sure to make a copy of the data first (or just use `<dataForColumn:>`/`<dataForColumnIndex:>`)
  232. If you don't, you're going to be in a world of hurt when you try and use the data.
  233. */
  234. - (NSData*)dataNoCopyForColumnIndex:(int)columnIdx NS_RETURNS_NOT_RETAINED;
  235. /** Is the column `NULL`?
  236. @param columnIdx Zero-based index for column.
  237. @return `YES` if column is `NULL`; `NO` if not `NULL`.
  238. */
  239. - (BOOL)columnIndexIsNull:(int)columnIdx;
  240. /** Is the column `NULL`?
  241. @param columnName `NSString` value of the name of the column.
  242. @return `YES` if column is `NULL`; `NO` if not `NULL`.
  243. */
  244. - (BOOL)columnIsNull:(NSString*)columnName;
  245. /** Returns a dictionary of the row results mapped to case sensitive keys of the column names.
  246. @returns `NSDictionary` of the row results.
  247. @warning The keys to the dictionary are case sensitive of the column names.
  248. */
  249. - (NSDictionary*)resultDictionary;
  250. /** Returns a dictionary of the row results
  251. @see resultDictionary
  252. @warning **Deprecated**: Please use `<resultDictionary>` instead. Also, beware that `<resultDictionary>` is case sensitive!
  253. */
  254. - (NSDictionary*)resultDict __attribute__ ((deprecated));
  255. ///-----------------------------
  256. /// @name Key value coding magic
  257. ///-----------------------------
  258. /** Performs `setValue` to yield support for key value observing.
  259. @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.
  260. */
  261. - (void)kvcMagic:(id)object;
  262. @end