]>
git.saurik.com Git - apple/xnu.git/blob - libkern/libkern/c++/OSNumber.h
ebb81a616850f1576d1ad4cf11ea88973f95498d
2 * Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
4 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
6 * This file contains Original Code and/or Modifications of Original Code
7 * as defined in and that are subject to the Apple Public Source License
8 * Version 2.0 (the 'License'). You may not use this file except in
9 * compliance with the License. The rights granted to you under the License
10 * may not be used to create, or enable the creation or redistribution of,
11 * unlawful or unlicensed copies of an Apple operating system, or to
12 * circumvent, violate, or enable the circumvention or violation of, any
13 * terms of an Apple operating system software license agreement.
15 * Please obtain a copy of the License at
16 * http://www.opensource.apple.com/apsl/ and read it before using this file.
18 * The Original Code and all software distributed under the License are
19 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
20 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
21 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
22 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
23 * Please see the License for the specific language governing rights and
24 * limitations under the License.
26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
28 /* IOOffset.h created by rsulack on Wed 17-Sep-1997 */
29 /* IOOffset.h converted to C++ by gvdl on Fri 1998-10-30 */
31 #ifndef _OS_OSNUMBER_H
32 #define _OS_OSNUMBER_H
34 #include <libkern/c++/OSObject.h>
40 * This header declares the OSNumber container class.
48 * OSNumber wraps an integer value in a C++ object
49 * for use in Libkern collections.
52 * OSNumber represents an integer of 8, 16, 32, or 64 bits
53 * as a Libkern C++ object.
54 * OSNumber objects are mutable: you can add to or set their values.
56 * <b>Use Restrictions</b>
58 * With very few exceptions in the I/O Kit, all Libkern-based C++
59 * classes, functions, and macros are <b>unsafe</b>
60 * to use in a primary interrupt context.
61 * Consult the I/O Kit documentation related to primary interrupts
62 * for more information.
64 * OSNumber provides no concurrency protection;
65 * it's up to the usage context to provide any protection necessary.
66 * Some portions of the I/O Kit, such as
67 * @link //apple_ref/doc/class/IORegistryEntry IORegistryEntry@/link,
68 * handle synchronization via defined member functions for setting
71 class OSNumber
: public OSObject
73 friend class OSSerialize
;
75 OSDeclareDefaultStructors(OSNumber
)
77 #if APPLE_KEXT_ALIGN_CONTAINERS
81 unsigned long long value
;
83 #else /* APPLE_KEXT_ALIGN_CONTAINERS */
86 unsigned long long value
;
89 struct ExpansionData
{ };
91 /* Reserved for future use. (Internal use only) */
92 ExpansionData
* reserved
;
94 #endif /* APPLE_KEXT_ALIGN_CONTAINERS */
99 * @function withNumber
102 * Creates and initializes an instance of OSNumber
103 * with an integer value.
105 * @param value The numeric integer value for the OSNumber to store.
106 * @param numberOfBits The number of bits to limit storage to.
109 * An instance of OSNumber with a reference count of 1;
110 * <code>NULL</code> on failure.
113 * <code>value</code> is masked to the provided <code>numberOfBits</code>
114 * when the OSNumber object is initialized.
116 * You can change the value of an OSNumber later
117 * using <code>@link setValue setValue@/link</code>
118 * and <code>@link addValue addValue@/link</code>,
119 * but you can't change the bit size.
121 static OSNumber
* withNumber(
122 unsigned long long value
,
123 unsigned int numberOfBits
);
127 * @function withNumber
130 * Creates and initializes an instance of OSNumber
131 * with an unsigned integer value represented as a C string.
133 * @param valueString A C string representing a numeric value
134 * for the OSNumber to store.
135 * @param numberOfBits The number of bits to limit storage to.
138 * An instance of OSNumber with a reference count of 1;
139 * <code>NULL</code> on failure.
142 * This function does not work in I/O Kit versions prior to 8.0 (Mac OS X 10.4).
143 * In I/O Kit version 8.0 and later, it works
144 * but is limited to parsing unsigned 32 bit quantities.
145 * The format of the C string may be decimal, hexadecimal ("0x" prefix),
146 * binary ("0b" prefix), or octal ("0" prefix).
148 * The parsed value is masked to the provided <code>numberOfBits</code>
149 * when the OSNumber object is initialized.
151 * You can change the value of an OSNumber later
152 * using <code>@link setValue setValue@/link</code>
153 * and <code>@link addValue addValue@/link</code>,
154 * but you can't change the bit size.
156 static OSNumber
* withNumber(
157 const char * valueString
,
158 unsigned int numberOfBits
);
165 * Initializes an instance of OSNumber with an integer value.
167 * @param value The numeric integer value for the OSNumber to store.
168 * @param numberOfBits The number of bits to limit storage to.
171 * <code>true</code> if initialization succeeds,
172 * <code>false</code> on failure.
175 * Not for general use. Use the static instance creation method
177 * //apple_ref/cpp/clm/OSNumber/withNumber/staticOSNumber*\/(constchar*,unsignedint)
178 * withNumber(unsigned long long, unsigned int)@/link</code>
182 unsigned long long value
,
183 unsigned int numberOfBits
);
190 * Initializes an instance of OSNumber
191 * with an unsigned integer value represented as a C string.
193 * @param valueString A C string representing a numeric value
194 * for the OSNumber to store.
195 * @param numberOfBits The number of bits to limit storage to.
198 * <code>true</code> if initialization succeeds,
199 * <code>false</code> on failure.
202 * Not for general use. Use the static instance creation method
204 * //apple_ref/cpp/clm/OSNumber/withNumber/staticOSNumber*\/(constchar*,unsignedint)
205 * withNumber(const char *, unsigned int)@/link</code>
209 const char * valueString
,
210 unsigned int numberOfBits
);
217 * Deallocates or releases any resources
218 * used by the OSNumber instance.
221 * This function should not be called directly;
224 * //apple_ref/cpp/instm/OSObject/release/virtualvoid/()
225 * release@/link</code>
228 virtual void free() APPLE_KEXT_OVERRIDE
;
232 * @function numberOfBits
235 * Returns the number of bits used to represent
236 * the OSNumber object's integer value.
239 * The number of bits used to represent
240 * the OSNumber object's integer value.
243 * The number of bits is used to limit the stored value of the OSNumber.
244 * Any change to its value is performed as an <code>unsigned long long</code>
245 * and then truncated to the number of bits.
247 virtual unsigned int numberOfBits() const;
251 * @function numberOfBytes
254 * Returns the number of bytes used to represent
255 * the OSNumber object's integer value.
258 * The number of bytes used to represent
259 * the OSNumber object's integer value.
260 * See <code>@link numberOfBits numberOfBits@/link</code>.
262 virtual unsigned int numberOfBytes() const;
265 // xx-review: should switch to explicitly-sized int types
266 // xx-review: but that messes up C++ mangled symbols :-(
270 * @function unsigned8BitValue
273 * Returns the OSNumber object's integer value
274 * cast as an unsigned 8-bit integer.
277 * The OSNumber object's integer value
278 * cast as an unsigned 8-bit integer.
281 * This function merely casts the internal integer value,
282 * giving no indication of truncation or other potential conversion problems.
284 virtual unsigned char unsigned8BitValue() const;
288 * @function unsigned16BitValue
291 * Returns the OSNumber object's integer value
292 * cast as an unsigned 16-bit integer.
295 * Returns the OSNumber object's integer value
296 * cast as an unsigned 16-bit integer.
299 * This function merely casts the internal integer value,
300 * giving no indication of truncation or other potential conversion problems.
302 virtual unsigned short unsigned16BitValue() const;
306 * @function unsigned32BitValue
309 * Returns the OSNumber object's integer value
310 * cast as an unsigned 32-bit integer.
313 * Returns the OSNumber object's integer value
314 * cast as an unsigned 32-bit integer.
317 * This function merely casts the internal integer value,
318 * giving no indication of truncation or other potential conversion problems.
320 virtual unsigned int unsigned32BitValue() const;
324 * @function unsigned64BitValue
327 * Returns the OSNumber object's integer value
328 * cast as an unsigned 64-bit integer.
331 * Returns the OSNumber object's integer value
332 * cast as an unsigned 64-bit integer.
335 * This function merely casts the internal integer value,
336 * giving no indication of truncation or other potential conversion problems.
338 virtual unsigned long long unsigned64BitValue() const;
340 // xx-review: wow, there's no addNumber(OSNumber *)!
346 * Adds a signed integer value to the internal integer value
347 * of the OSNumber object.
349 * @param value The value to be added.
352 * This function adds values as 64-bit integers,
353 * but masks the result by the bit size
354 * (see <code>@link numberOfBits numberOfBits@/link</code>),
355 * so addition overflows will not necessarily
356 * be the same as for plain C integers.
358 virtual void addValue(signed long long value
);
365 * Replaces the current internal integer value
366 * of the OSNumber object by the value given.
368 * @param value The new value for the OSNumber object,
369 * which is truncated by the bit size of the OSNumber object
370 * (see <code>@link numberOfBits numberOfBits@/link</code>).
372 virtual void setValue(unsigned long long value
);
376 * @function isEqualTo
379 * Tests the equality of two OSNumber objects.
381 * @param aNumber The OSNumber to be compared against the receiver.
384 * <code>true</code> if the OSNumber objects are equal,
385 * <code>false</code> if not.
388 * Two OSNumber objects are considered equal
389 * if they represent the same C integer value.
391 virtual bool isEqualTo(const OSNumber
* aNumber
) const;
395 * @function isEqualTo
398 * Tests the equality an OSNumber to an arbitrary object.
400 * @param anObject An object to be compared against the receiver.
403 * <code>true</code> if the objects are equal,
404 * <code>false</code> if not.
407 * An OSNumber is considered equal to another object if that object is
408 * derived from OSNumber and represents the same C integer value.
410 virtual bool isEqualTo(const OSMetaClassBase
* anObject
) const APPLE_KEXT_OVERRIDE
;
414 * @function serialize
417 * Archives the receiver into the provided
418 * @link //apple_ref/doc/class/OSSerialize OSSerialize@/link object.
420 * @param serializer The OSSerialize object.
423 * <code>true</code> if serialization succeeds, <code>false</code> if not.
425 virtual bool serialize(OSSerialize
* serializer
) const APPLE_KEXT_OVERRIDE
;
428 OSMetaClassDeclareReservedUnused(OSNumber
, 0);
429 OSMetaClassDeclareReservedUnused(OSNumber
, 1);
430 OSMetaClassDeclareReservedUnused(OSNumber
, 2);
431 OSMetaClassDeclareReservedUnused(OSNumber
, 3);
432 OSMetaClassDeclareReservedUnused(OSNumber
, 4);
433 OSMetaClassDeclareReservedUnused(OSNumber
, 5);
434 OSMetaClassDeclareReservedUnused(OSNumber
, 6);
435 OSMetaClassDeclareReservedUnused(OSNumber
, 7);
438 #endif /* !_OS_OSNUMBER_H */