libkern/libkern/c++/OSNumber.h

   1 /*
   2  * Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
   5  *
   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.
  14  *
  15  * Please obtain a copy of the License at
  16  * http://www.opensource.apple.com/apsl/ and read it before using this file.
  17  *
  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.
  25  *
  26  * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
  27  */
  28 /* IOOffset.h created by rsulack on Wed 17-Sep-1997 */
  29 /* IOOffset.h converted to C++ by gvdl on Fri 1998-10-30 */
  30
  31 #ifndef _OS_OSNUMBER_H
  32 #define _OS_OSNUMBER_H
  33
  34 #include <libkern/c++/OSObject.h>
  35
  36 /*!
  37  * @header
  38  *
  39  * @abstract
  40  * This header declares the OSNumber container class.
  41  */
  42
  43
  44 /*!
  45  * @class OSNumber
  46  *
  47  * @abstract
  48  * OSNumber wraps an integer value in a C++ object
  49  * for use in Libkern collections.
  50  *
  51  * @discussion
  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.
  55  *
  56  * <b>Use Restrictions</b>
  57  *
  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.
  63  *
  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
  69  * properties.
  70  */
  71 class OSNumber : public OSObject
  72 {
  73     OSDeclareDefaultStructors(OSNumber)
  74
  75 protected:
  76     unsigned long long value;
  77     unsigned int size;
  78
  79     struct ExpansionData { };
  80
  81     /* Reserved for future use.  (Internal use only)  */
  82     ExpansionData * reserved;
  83
  84 public:
  85
  86
  87    /*!
  88     * @function withNumber
  89     *
  90     * @abstract
  91     * Creates and initializes an instance of OSNumber
  92     * with an integer value.
  93     *
  94     * @param value        The numeric integer value for the OSNumber to store.
  95     * @param numberOfBits The number of bits to limit storage to.
  96     *
  97     * @result
  98     * An instance of OSNumber with a reference count of 1;
  99     * <code>NULL</code> on failure.
 100     *
 101     * @discussion
 102     * <code>value</code> is masked to the provided <code>numberOfBits</code>
 103     * when the OSNumber object is initialized.
 104     *
 105     * You can change the value of an OSNumber later
 106     * using <code>@link setValue setValue@/link</code>
 107     * and <code>@link addValue addValue@/link</code>,
 108     * but you can't change the bit size.
 109     */
 110     static OSNumber * withNumber(
 111         unsigned long long value,
 112         unsigned int       numberOfBits);
 113
 114
 115    /*!
 116     * @function withNumber
 117     *
 118     * @abstract
 119     * Creates and initializes an instance of OSNumber
 120     * with an unsigned integer value represented as a C string.
 121     *
 122     * @param valueString  A C string representing a numeric value
 123     *                     for the OSNumber to store.
 124     * @param numberOfBits The number of bits to limit storage to.
 125     *
 126     * @result
 127     * An instance of OSNumber with a reference count of 1;
 128     * <code>NULL</code> on failure.
 129     *
 130     * @discussion
 131     * This function does not work in I/O Kit versions prior to 8.0 (Mac OS X 10.4).
 132     * In I/O Kit version 8.0 and later, it works
 133     * but is limited to parsing unsigned 32 bit quantities.
 134     * The format of the C string may be decimal, hexadecimal ("0x" prefix),
 135     * binary ("0b" prefix), or octal ("0" prefix).
 136     *
 137     * The parsed value is masked to the provided <code>numberOfBits</code>
 138     * when the OSNumber object is initialized.
 139     *
 140     * You can change the value of an OSNumber later
 141     * using <code>@link setValue setValue@/link</code>
 142     * and <code>@link addValue addValue@/link</code>,
 143     * but you can't change the bit size.
 144     */
 145     static OSNumber * withNumber(
 146         const char   * valueString,
 147         unsigned int   numberOfBits);
 148
 149
 150    /*!
 151     * @function init
 152     *
 153     * @abstract
 154     * Initializes an instance of OSNumber with an integer value.
 155     *
 156     * @param value        The numeric integer value for the OSNumber to store.
 157     * @param numberOfBits The number of bits to limit storage to.
 158     *
 159     * @result
 160     * <code>true</code> if initialization succeeds,
 161     * <code>false</code> on failure.
 162     *
 163     * @discussion
 164     * Not for general use. Use the static instance creation method
 165     * <code>@link
 166     * //apple_ref/cpp/clm/OSNumber/withNumber/staticOSNumber*\/(constchar*,unsignedint)
 167     * withNumber(unsigned long long, unsigned int)@/link</code>
 168     * instead.
 169     */
 170     virtual bool init(
 171         unsigned long long value,
 172         unsigned int       numberOfBits);
 173
 174
 175    /*!
 176     * @function init
 177     *
 178     * @abstract
 179     * Initializes an instance of OSNumber
 180     * with an unsigned integer value represented as a C string.
 181     *
 182     * @param valueString  A C string representing a numeric value
 183     *                     for the OSNumber to store.
 184     * @param numberOfBits The number of bits to limit storage to.
 185     *
 186     * @result
 187     * <code>true</code> if initialization succeeds,
 188     * <code>false</code> on failure.
 189     *
 190     * @discussion
 191     * Not for general use. Use the static instance creation method
 192     * <code>@link
 193     * //apple_ref/cpp/clm/OSNumber/withNumber/staticOSNumber*\/(constchar*,unsignedint)
 194     * withNumber(const char *, unsigned int)@/link</code>
 195     * instead.
 196     */
 197     virtual bool init(
 198         const char   * valueString,
 199         unsigned int   numberOfBits);
 200
 201
 202    /*!
 203     * @function free
 204     *
 205     * @abstract
 206     * Deallocates or releases any resources
 207     * used by the OSNumber instance.
 208     *
 209     * @discussion
 210     * This function should not be called directly;
 211     * use
 212     * <code>@link
 213     * //apple_ref/cpp/instm/OSObject/release/virtualvoid/()
 214     * release@/link</code>
 215     * instead.
 216     */
 217     virtual void free();
 218
 219
 220    /*!
 221     * @function numberOfBits
 222     *
 223     * @abstract
 224     * Returns the number of bits used to represent
 225     * the OSNumber object's integer value.
 226     *
 227     * @result
 228     * The number of bits used to represent
 229     * the OSNumber object's integer value.
 230     *
 231     * @discussion
 232     * The number of bits is used to limit the stored value of the OSNumber.
 233     * Any change to its value is performed as an <code>unsigned long long</code>
 234     * and then truncated to the number of bits.
 235     */
 236     virtual unsigned int numberOfBits() const;
 237
 238
 239    /*!
 240     * @function numberOfBytes
 241     *
 242     * @abstract
 243     * Returns the number of bytes used to represent
 244     * the OSNumber object's integer value.
 245     *
 246     * @result
 247     * The number of bytes used to represent
 248     * the OSNumber object's integer value.
 249     * See <code>@link numberOfBits numberOfBits@/link</code>.
 250     */
 251     virtual unsigned int numberOfBytes() const;
 252
 253
 254 // xx-review: should switch to explicitly-sized int types
 255 // xx-review: but that messes up C++ mangled symbols :-(
 256
 257
 258    /*!
 259     * @function unsigned8BitValue
 260     *
 261     * @abstract
 262     * Returns the OSNumber object's integer value
 263     * cast as an unsigned 8-bit integer.
 264     *
 265     * @result
 266     * The OSNumber object's integer value
 267     * cast as an unsigned 8-bit integer.
 268     *
 269     * @discussion
 270     * This function merely casts the internal integer value,
 271     * giving no indication of truncation or other potential conversion problems.
 272     */
 273     virtual unsigned char unsigned8BitValue() const;
 274
 275
 276    /*!
 277     * @function unsigned16BitValue
 278     *
 279     * @abstract
 280     * Returns the OSNumber object's integer value
 281     * cast as an unsigned 16-bit integer.
 282     *
 283     * @result
 284     * Returns the OSNumber object's integer value
 285     * cast as an unsigned 16-bit integer.
 286     *
 287     * @discussion
 288     * This function merely casts the internal integer value,
 289     * giving no indication of truncation or other potential conversion problems.
 290     */
 291     virtual unsigned short unsigned16BitValue() const;
 292
 293
 294    /*!
 295     * @function unsigned32BitValue
 296     *
 297     * @abstract
 298     * Returns the OSNumber object's integer value
 299     * cast as an unsigned 32-bit integer.
 300     *
 301     * @result
 302     * Returns the OSNumber object's integer value
 303     * cast as an unsigned 32-bit integer.
 304     *
 305     * @discussion
 306     * This function merely casts the internal integer value,
 307     * giving no indication of truncation or other potential conversion problems.
 308     */
 309     virtual unsigned int unsigned32BitValue() const;
 310
 311
 312    /*!
 313     * @function unsigned64BitValue
 314     *
 315     * @abstract
 316     * Returns the OSNumber object's integer value
 317     * cast as an unsigned 64-bit integer.
 318     *
 319     * @result
 320     * Returns the OSNumber object's integer value
 321     * cast as an unsigned 64-bit integer.
 322     *
 323     * @discussion
 324     * This function merely casts the internal integer value,
 325     * giving no indication of truncation or other potential conversion problems.
 326     */
 327     virtual unsigned long long unsigned64BitValue() const;
 328
 329 // xx-review: wow, there's no addNumber(OSNumber *)!
 330
 331    /*!
 332     * @function addValue
 333     *
 334     * @abstract
 335     * Adds a signed integer value to the internal integer value
 336     * of the OSNumber object.
 337     *
 338     * @param value  The value to be added.
 339     *
 340     * @discussion
 341     * This function adds values as 64-bit integers,
 342     * but masks the result by the bit size
 343     * (see <code>@link numberOfBits numberOfBits@/link</code>),
 344     * so addition overflows will not necessarily
 345     * be the same as for plain C integers.
 346     */
 347     virtual void addValue(signed long long value);
 348
 349
 350    /*!
 351     * @function setValue
 352     *
 353     * @abstract
 354     * Replaces the current internal integer value
 355     * of the OSNumber object by the value given.
 356     *
 357     * @param value  The new value for the OSNumber object,
 358     *               which is truncated by the bit size of the OSNumber object
 359     *               (see <code>@link numberOfBits numberOfBits@/link</code>).
 360     */
 361     virtual void setValue(unsigned long long value);
 362
 363
 364    /*!
 365     * @function isEqualTo
 366     *
 367     * @abstract
 368     * Tests the equality of two OSNumber objects.
 369     *
 370     * @param aNumber     The OSNumber to be compared against the receiver.
 371     *
 372     * @result
 373     * <code>true</code> if the OSNumber objects are equal,
 374     * <code>false</code> if not.
 375     *
 376     * @discussion
 377     * Two OSNumber objects are considered equal
 378     * if they represent the same C integer value.
 379     */
 380     virtual bool isEqualTo(const OSNumber * aNumber) const;
 381
 382
 383    /*!
 384     * @function isEqualTo
 385     *
 386     * @abstract
 387     * Tests the equality an OSNumber to an arbitrary object.
 388     *
 389     * @param anObject An object to be compared against the receiver.
 390     *
 391     * @result
 392     * <code>true</code> if the objects are equal,
 393     * <code>false</code> if not.
 394     *
 395     * @discussion
 396     * An OSNumber is considered equal to another object if that object is
 397     * derived from OSNumber and represents the same C integer value.
 398     */
 399     virtual bool isEqualTo(const OSMetaClassBase * anObject) const;
 400
 401
 402    /*!
 403     * @function serialize
 404     *
 405     * @abstract
 406     * Archives the receiver into the provided
 407     * @link //apple_ref/doc/class/OSSerialize OSSerialize@/link object.
 408     *
 409     * @param serializer The OSSerialize object.
 410     *
 411     * @result
 412     * <code>true</code> if serialization succeeds, <code>false</code> if not.
 413     */
 414     virtual bool serialize(OSSerialize * serializer) const;
 415
 416
 417     OSMetaClassDeclareReservedUnused(OSNumber, 0);
 418     OSMetaClassDeclareReservedUnused(OSNumber, 1);
 419     OSMetaClassDeclareReservedUnused(OSNumber, 2);
 420     OSMetaClassDeclareReservedUnused(OSNumber, 3);
 421     OSMetaClassDeclareReservedUnused(OSNumber, 4);
 422     OSMetaClassDeclareReservedUnused(OSNumber, 5);
 423     OSMetaClassDeclareReservedUnused(OSNumber, 6);
 424     OSMetaClassDeclareReservedUnused(OSNumber, 7);
 425 };
 426
 427 #endif /* !_OS_OSNUMBER_H */