1 /* Interface for NSValue for GNUStep 2 Copyright (C) 1995, 1996 Free Software Foundation, Inc. 3 4 Written by: Adam Fedor <fedor@boulder.colorado.edu> 5 Created: 1995 6 7 This file is part of the GNUstep Base Library. 8 9 This library is free software; you can redistribute it and/or 10 modify it under the terms of the GNU Lesser General Public 11 License as published by the Free Software Foundation; either 12 version 2 of the License, or (at your option) any later version. 13 14 This library is distributed in the hope that it will be useful, 15 but WITHOUT ANY WARRANTY; without even the implied warranty of 16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 17 Lesser General Public License for more details. 18 19 You should have received a copy of the GNU Lesser General Public 20 License along with this library; if not, write to the Free 21 Software Foundation, Inc., 51 Franklin Street, Fifth Floor, 22 Boston, MA 02110 USA. 23 */ 24 25 #ifndef __NSValue_h_GNUSTEP_BASE_INCLUDE 26 #define __NSValue_h_GNUSTEP_BASE_INCLUDE 27 #import <GNUstepBase/GSVersionMacros.h> 28 29 #import <Foundation/NSObject.h> 30 #import <Foundation/NSGeometry.h> 31 #import <Foundation/NSRange.h> 32 33 #if defined(__cplusplus) 34 extern "C" { 35 #endif 36 37 @class NSString; 38 39 /** 40 * The <code>NSValue</code> class can wrap a single primitive value as an 41 * object so it can be used in the containers and other places where an object 42 * reference is needed. Once initialized, an <code>NSValue</code> is 43 * immutable, and there is no <code>NSMutableValue</code> class. You 44 * initialize it by giving it a pointer to the primitive value, and you should 45 * be careful this does not get freed until after the <code>NSValue</code> is 46 * no longer used. 47 */ 48 @interface NSValue : NSObject <NSCopying, NSCoding> 49 50 // Allocating and Initializing 51 52 /** 53 * Create new instance with specified value (a pointer) of given type, which 54 * is a string code obtainable through the compile-time operator 55 * <code>@encode(...)</code>. For example: 56 <example> 57 NSValue *theValue = [NSValue value: &n withObjCType: @encode(int)]; 58 </example> 59 */ 60 + (NSValue*) value: (const void*)value withObjCType: (const char*)type; 61 62 /** 63 * Create new instance holding anObject. This is useful if you want to add 64 * anObject to a collection such as [NSArray] but don't want it to be retained 65 * (a weak reference). 66 */ 67 + (NSValue*) valueWithNonretainedObject: (id)anObject; 68 69 /** 70 * Convenience method to create instance holding an <code>NSPoint</code> 71 * structure. 72 */ 73 + (NSValue*) valueWithPoint: (NSPoint)point; 74 75 /** 76 * Convenience method to create instance holding a pointer. Same as 77 * using <code>@encode(void *)</code> in +value:withObjCType: . 78 */ 79 + (NSValue*) valueWithPointer: (const void*)pointer; 80 81 /** 82 * Convenience method to create instance holding an <code>NSRange</code> 83 * structure. 84 */ 85 + (NSValue*) valueWithRange: (NSRange)range; 86 87 /** 88 * Convenience method to create instance holding an <code>NSRect</code> 89 * structure. 90 */ 91 + (NSValue*) valueWithRect: (NSRect)rect; 92 93 /** 94 * Convenience method to create instance holding an <code>NSSize</code> 95 * structure. 96 */ 97 + (NSValue*) valueWithSize: (NSSize)size; 98 99 #if OS_API_VERSION(GS_API_MACOSX, GS_API_LATEST) 100 /** 101 * Synonym for value:withObjCType: . 102 */ 103 + (NSValue*) valueWithBytes: (const void*)value objCType: (const char*)type; 104 105 /** <init/> 106 * Initialize with value of type, parallel to value:withObjCType: . 107 */ 108 - (id) initWithBytes: (const void*)data objCType: (const char*)type; 109 110 /** 111 * Compares this instance to another <code>NSValue</code>. For equality, 112 * both contents and declared type of the two values must match. 113 */ 114 - (BOOL) isEqualToValue: (NSValue*)other; 115 #endif /* GS_API_MACOSX */ 116 117 // Accessing Data 118 119 /** 120 * Copies bytes from the pointer receiver was initialized with into buffer 121 * pointed to by value. Number of bytes copied is determined by the type. If 122 * type was a void * pointer or object id, the memory address itself is 123 * copied. 124 */ 125 - (void) getValue: (void*)value; 126 127 /** 128 * Returns the string <code>@encode(...)</code> compatible type the receiver 129 * was initialized with. 130 */ 131 - (const char*) objCType; 132 133 /** 134 * If receiver was initialized with an object ID, return it, else raises 135 * <code>NSInternalInconsistencyException</code>. 136 */ 137 - (id) nonretainedObjectValue; 138 139 /** 140 * If receiver was initialized with a void * pointer, return it, else raises 141 * <code>NSInternalInconsistencyException</code>. 142 */ 143 - (void*) pointerValue; 144 145 /** 146 * If receiver was initialized with an <code>NSRange</code> value, return it, 147 * else raises <code>NSInternalInconsistencyException</code>. 148 */ 149 - (NSRange) rangeValue; 150 151 /** 152 * If receiver was initialized with an <code>NSRect</code> value, return it, 153 * else raises <code>NSInternalInconsistencyException</code>. 154 */ 155 - (NSRect) rectValue; 156 157 /** 158 * If receiver was initialized with an <code>NSSize</code> value, return it, 159 * else raises <code>NSInternalInconsistencyException</code>. 160 */ 161 - (NSSize) sizeValue; 162 163 /** 164 * If receiver was initialized with an <code>NSPoint</code> value, return it, 165 * else raises <code>NSInternalInconsistencyException</code>. 166 */ 167 - (NSPoint) pointValue; 168 169 @end 170 171 /** 172 * Subclass of [NSValue] offering convenience methods for initializing from 173 * and accessing as any C primitive numeric type. On access, the value will 174 * be type-converted if necessary, using standard C conversion rules. 175 */ 176 @interface NSNumber : NSValue <NSCopying,NSCoding> 177 178 // Allocating and Initializing 179 180 /** New instance from boolean value. */ 181 + (NSNumber*) numberWithBool: (BOOL)value; 182 /** New instance from signed char value. */ 183 + (NSNumber*) numberWithChar: (signed char)value; 184 /** New instance from double value. */ 185 + (NSNumber*) numberWithDouble: (double)value; 186 /** New instance from float value. */ 187 + (NSNumber*) numberWithFloat: (float)value; 188 /** New instance from (signed) int value. */ 189 + (NSNumber*) numberWithInt: (signed int)value; 190 /** New instance from (signed) long value. */ 191 + (NSNumber*) numberWithLong: (signed long)value; 192 /** New instance from (signed) long long value. */ 193 + (NSNumber*) numberWithLongLong: (signed long long)value; 194 /** New instance from (signed) short value. */ 195 + (NSNumber*) numberWithShort: (signed short)value; 196 /** New instance from unsigned char value. */ 197 + (NSNumber*) numberWithUnsignedChar: (unsigned char)value; 198 /** New instance from unsigned int value. */ 199 + (NSNumber*) numberWithUnsignedInt: (unsigned int)value; 200 /** New instance from unsigned long value. */ 201 + (NSNumber*) numberWithUnsignedLong: (unsigned long)value; 202 /** New instance from unsigned long long value. */ 203 + (NSNumber*) numberWithUnsignedLongLong: (unsigned long long)value; 204 /** New instance from unsigned short value. */ 205 + (NSNumber*) numberWithUnsignedShort: (unsigned short)value; 206 207 /** Initialize from boolean value. */ 208 - (id) initWithBool: (BOOL)value; 209 /** Initialize from signed char value. */ 210 - (id) initWithChar: (signed char)value; 211 /** Initialize from double value. */ 212 - (id) initWithDouble: (double)value; 213 /** Initialize from float value. */ 214 - (id) initWithFloat: (float)value; 215 /** Initialize from (signed) int value. */ 216 - (id) initWithInt: (signed int)value; 217 /** Initialize from (signed) long value. */ 218 - (id) initWithLong: (signed long)value; 219 /** Initialize from (signed) long long value. */ 220 - (id) initWithLongLong: (signed long long)value; 221 /** Initialize from (signed) short value. */ 222 - (id) initWithShort: (signed short)value; 223 /** Initialize from unsigned char value. */ 224 - (id) initWithUnsignedChar: (unsigned char)value; 225 /** Initialize from unsigned int value. */ 226 - (id) initWithUnsignedInt: (unsigned int)value; 227 /** Initialize from unsigned long value. */ 228 - (id) initWithUnsignedLong: (unsigned long)value; 229 /** Initialize from unsigned long long value. */ 230 - (id) initWithUnsignedLongLong: (unsigned long long)value; 231 /** Initialize from unsigned short value. */ 232 - (id) initWithUnsignedShort: (unsigned short)value; 233 234 // Accessing Data 235 236 /** 237 * Return value as a BOOL; this will in fact be a char value converted 238 * if necessary from type initialized with; if you wish to consider anything 239 * nonzero TRUE do not compare directly to YES, but use <code>'!= NO'</code>. 240 */ 241 - (BOOL) boolValue; 242 /** Returns value as a signed char, converting if necessary. */ 243 - (signed char) charValue; 244 /** Returns value as a double, converting if necessary. */ 245 - (double) doubleValue; 246 /** Returns value as a float, converting if necessary. */ 247 - (float) floatValue; 248 /** Returns value as a (signed) int, converting if necessary. */ 249 - (signed int) intValue; 250 /** Returns value as a (signed) long, converting if necessary. */ 251 - (signed long) longValue; 252 /** Returns value as a (signed) long long, converting if necessary. */ 253 - (signed long long) longLongValue; 254 /** Returns value as a (signed) short, converting if necessary. */ 255 - (signed short) shortValue; 256 /** Returns value as an unsigned char, converting if necessary. */ 257 - (unsigned char) unsignedCharValue; 258 /** Returns value as an unsigned int, converting if necessary. */ 259 - (unsigned int) unsignedIntValue; 260 /** Returns value as an unsigned long, converting if necessary. */ 261 - (unsigned long) unsignedLongValue; 262 /** Returns value as an unsigned long long, converting if necessary. */ 263 - (unsigned long long) unsignedLongLongValue; 264 /** Returns value as an unsigned short, converting if necessary. */ 265 - (unsigned short) unsignedShortValue; 266 267 /** Returns -description . */ 268 - (NSString*) stringValue; 269 270 /** 271 * Returns the string representation of this number using a non-localised 272 * conversion (decimal point is '.' irrespective of the locale). 273 */ 274 - (NSString*) description; 275 276 /** 277 * <p> 278 * Produces a string representation of the number. For a boolean 279 * this will be either 'true' or 'false'. For other numbers the 280 * format is produced using the initWithFormat:locale:... method 281 * of NSString, and the format depends on the type of number as 282 * follows - 283 * </p> 284 * <deflist> 285 * <term>char</term> 286 * <desc>%i</desc> 287 * <term> short</term> 288 * <desc>%hi</desc> 289 * <term> int</term> 290 * <desc>%i</desc> 291 * <term> long</term> 292 * <desc>%li</desc> 293 * <term> long long</term> 294 * <desc>%lli</desc> 295 * <term> unsigned char</term> 296 * <desc>%u</desc> 297 * <term> unsigned short</term> 298 * <desc>%hu</desc> 299 * <term> unsigned int</term> 300 * <desc>%u</desc> 301 * <term> unsigned long</term> 302 * <desc>%lu</desc> 303 * <term> unsigned long long</term> 304 * <desc>%llu</desc> 305 * <term> float</term> 306 * <desc>%0.7g</desc> 307 * <term> double</term> 308 * <desc>%0.16g</desc> 309 * </deflist> 310 */ 311 - (NSString*) descriptionWithLocale: (id)locale; 312 313 /** 314 * Compares receiver with otherNumber, using C type conversion if necessary, 315 * and returns <code>NSOrderedAscending</code>, 316 * <code>NSOrderedDescending</code>, or <code>NSOrderedSame</code> depending 317 * on whether it is less than, greater than, or equal to otherNumber. 318 */ 319 - (NSComparisonResult) compare: (NSNumber*)otherNumber; 320 321 /** 322 * Returns whether receiver and otherNumber represent the same numerical value. 323 */ 324 - (BOOL) isEqualToNumber: (NSNumber*)otherNumber; 325 326 327 #if OS_API_VERSION(MAC_OS_X_VERSION_10_5, GS_API_LATEST) 328 /** Return a number intialised with NSInteger. 329 */ 330 + (NSNumber*) numberWithInteger: (NSInteger)value; 331 /** Return a number intialised with NSUInteger. 332 */ 333 + (NSNumber*) numberWithUnsignedInteger: (NSUInteger)value; 334 /** Initialise the receiver with NSInteger content. 335 */ 336 - (id) initWithInteger: (NSInteger)value; 337 /** Initialise the receiver with NSUInteger content. 338 */ 339 - (id) initWithUnsignedInteger: (NSUInteger)value; 340 /** Return the contents of the receiver as NSInteger. 341 */ 342 - (NSInteger) integerValue; 343 /** Return the contents of the receiver as NSUInteger. 344 */ 345 - (NSUInteger) unsignedIntegerValue; 346 #endif 347 348 @end 349 350 #if OS_API_VERSION(GS_API_NONE, GS_API_NONE) 351 352 /** Note: Defines a method that is not in the OpenStep spec, but makes 353 subclassing easier. */ 354 @interface NSValue (Subclassing) 355 356 /** Used by value: withObjCType: to determine the concrete subclass to alloc. */ 357 + (Class) valueClassWithObjCType: (const char*)type; 358 359 @end 360 #endif 361 362 #if defined(__cplusplus) 363 } 364 #endif 365 366 #if !NO_GNUSTEP && !defined(GNUSTEP_BASE_INTERNAL) 367 #import <GNUstepBase/NSNumber+GNUstepBase.h> 368 #endif 369 370 #endif /* __NSValue_h_GNUSTEP_BASE_INCLUDE */ 371