/BlocksKit/NSObject+AssociatedObjects.h

http://github.com/zwaldowski/BlocksKit · C++ Header · 114 lines · 13 code · 13 blank · 88 comment · 0 complexity · 1bf4d9a6df1564a11ab84ccbffeca9e1 MD5 · raw file

  1. //
  2. // NSObject+AssociatedObjects.h
  3. // %PROJECT
  4. //
  5. #import "BKGlobals.h"
  6. /** Objective-C wrapper for 10.6 associated object API.
  7. In Mac OS X Snow Leopard and iOS 3.0, Apple introduced an
  8. addition to the Objective-C Runtime called associated objects.
  9. Associated objects allow for the pairing of a random key and
  10. object pair to be saved on an instance.
  11. In BlocksKit, associated objects allow us to emulate instance
  12. variables in the categories we use.
  13. Class methods also exist for each association. These associations
  14. are unique to each class, and exist for the lifetime of the
  15. application unless set to `nil`. Each class is a unique meta-object;
  16. the ultimate singleton.
  17. Created by Andy Matuschak as [AMAssociatedObjects](https://github.com/andymatuschak/NSObject-AssociatedObjects).
  18. Licensed in the public domain.
  19. */
  20. @interface NSObject (AssociatedObjects)
  21. /** Strongly associates an object with the reciever.
  22. The associated value is retained as if it were a property
  23. synthesized with `nonatomic` and `retain`.
  24. Using retained association is strongly recommended for most
  25. Objective-C object derivative of NSObject, particularly
  26. when it is subject to being externally released or is in an
  27. `NSAutoreleasePool`.
  28. @param value Any object.
  29. @param key A unique key pointer.
  30. */
  31. - (void)associateValue:(id)value withKey:(const char *)key;
  32. /** Strongly associates an object with the receiving class.
  33. @see associateValue:withKey:
  34. @param value Any object.
  35. @param key A unique key pointer.
  36. */
  37. + (void)associateValue:(id)value withKey:(const char *)key;
  38. /** Associates a copy of an object with the reciever.
  39. The associated value is copied as if it were a property
  40. synthesized with `nonatomic` and `copy`.
  41. Using copied association is recommended for a block or
  42. otherwise `NSCopying`-compliant instances like NSString.
  43. @param value Any object, pointer, or value.
  44. @param key A unique key pointer.
  45. */
  46. - (void)associateCopyOfValue:(id)value withKey:(const char *)key;
  47. /** Associates a copy of an object with the receiving class.
  48. @see associateCopyOfValue:withKey:
  49. @param value Any object, pointer, or value.
  50. @param key A unique key pointer.
  51. */
  52. + (void)associateCopyOfValue:(id)value withKey:(const char *)key;
  53. /** Weakly associates an object with the reciever.
  54. A weak association will cause the pointer to be set to zero
  55. or nil upon the disappearance of what it references;
  56. in other words, the associated object is not kept alive.
  57. @param value Any object.
  58. @param key A unique key pointer.
  59. */
  60. - (void)weaklyAssociateValue:(id)value withKey:(const char *)key;
  61. /** Weakly associates an object with the receiving class.
  62. @see weaklyAssociateValue:withKey:
  63. @param value Any object.
  64. @param key A unique key pointer.
  65. */
  66. + (void)weaklyAssociateValue:(id)value withKey:(const char *)key;
  67. /** Returns the associated value for a key on the reciever.
  68. @param key A unique key pointer.
  69. @return The object associated with the key, or `nil` if not found.
  70. */
  71. - (id)associatedValueForKey:(const char *)key;
  72. /** Returns the associated value for a key on the receiving class.
  73. @see associatedValueForKey:
  74. @param key A unique key pointer.
  75. @return The object associated with the key, or `nil` if not found.
  76. */
  77. + (id)associatedValueForKey:(const char *)key;
  78. /** Returns the reciever to a clean state by removing all
  79. associated objects, releasing them if necessary. */
  80. - (void)removeAllAssociatedObjects;
  81. /** Returns the recieving class to a clean state by removing
  82. all associated objects, releasing them if necessary. */
  83. + (void)removeAllAssociatedObjects;
  84. @end