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 Library 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 02111 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 "NSObject.h"
30 #import "NSGeometry.h"
31 #import "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 */