OSNumber

Inherits from
OSObject
Availability
Available in OS X v10.0 and later.
Declared in
OSNumber.h

Overview

OSNumber wraps an integer value in a C++ object for use in Libkern collections.

OSNumber represents an integer of 8, 16, 32, or 64 bits as a Libkern C++ object. OSNumber objects are mutable: you can add to or set their values.

Use Restrictions

With very few exceptions in the I/O Kit, all Libkern-based C++ classes, functions, and macros are unsafe to use in a primary interrupt context. Consult the I/O Kit documentation related to primary interrupts for more information.

OSNumber provides no concurrency protection; it's up to the usage context to provide any protection necessary. Some portions of the I/O Kit, such as IORegistryEntry, handle synchronization via defined member functions for setting properties.

Tasks

Miscellaneous

Instance Methods

addValue

Adds a signed integer value to the internal integer value of the OSNumber object.

virtual void addValue( signed long long value);
Parameters
value

The value to be added.

Discussion

This function adds values as 64-bit integers, but masks the result by the bit size (see numberOfBits), so addition overflows will not necessarily be the same as for plain C integers.

free

Deallocates or releases any resources used by the OSNumber instance.

virtual void free();
Discussion

This function should not be called directly; use release instead.

init(const char *, unsigned int)

Initializes an instance of OSNumber with an unsigned integer value represented as a C string.

virtual bool init( const char *valueString, unsigned int numberOfBits);
Parameters
valueString

A C string representing a numeric value for the OSNumber to store.

numberOfBits

The number of bits to limit storage to.

Return Value

true if initialization succeeds, false on failure.

Discussion

Not for general use. Use the static instance creation method withNumber(const char *, unsigned int) instead.

init(unsigned long long, unsigned int)

Initializes an instance of OSNumber with an integer value.

virtual bool init( unsigned long long value, unsigned int numberOfBits);
Parameters
value

The numeric integer value for the OSNumber to store.

numberOfBits

The number of bits to limit storage to.

Return Value

true if initialization succeeds, false on failure.

Discussion

Not for general use. Use the static instance creation method withNumber(unsigned long long, unsigned int) instead.

isEqualTo(const OSMetaClassBase *)

Tests the equality an OSNumber to an arbitrary object.

virtual bool isEqualTo( const OSMetaClassBase *anObject) const;
Parameters
anObject

An object to be compared against the receiver.

Return Value

true if the objects are equal, false if not.

Discussion

An OSNumber is considered equal to another object if that object is derived from OSNumber and represents the same C integer value.

isEqualTo(const OSNumber *)

Tests the equality of two OSNumber objects.

virtual bool isEqualTo( const OSNumber *aNumber) const;
Parameters
aNumber

The OSNumber to be compared against the receiver.

Return Value

true if the OSNumber objects are equal, false if not.

Discussion

Two OSNumber objects are considered equal if they represent the same C integer value.

numberOfBits

Returns the number of bits used to represent the OSNumber object's integer value.

virtual unsigned int numberOfBits() const;
Return Value

The number of bits used to represent the OSNumber object's integer value.

Discussion

The number of bits is used to limit the stored value of the OSNumber. Any change to its value is performed as an unsigned long long and then truncated to the number of bits.

numberOfBytes

Returns the number of bytes used to represent the OSNumber object's integer value.

virtual unsigned int numberOfBytes() const;
Return Value

The number of bytes used to represent the OSNumber object's integer value. See numberOfBits.

serialize

Archives the receiver into the provided OSSerialize object.

virtual bool serialize( OSSerialize *serializer) const;
Parameters
serializer

The OSSerialize object.

Return Value

true if serialization succeeds, false if not.

setValue

Replaces the current internal integer value of the OSNumber object by the value given.

virtual void setValue( unsigned long long value);
Parameters
value

The new value for the OSNumber object, which is truncated by the bit size of the OSNumber object (see numberOfBits).

unsigned16BitValue

Returns the OSNumber object's integer value cast as an unsigned 16-bit integer.

virtual unsigned short unsigned16BitValue() const;
Return Value

Returns the OSNumber object's integer value cast as an unsigned 16-bit integer.

Discussion

This function merely casts the internal integer value, giving no indication of truncation or other potential conversion problems.

unsigned32BitValue

Returns the OSNumber object's integer value cast as an unsigned 32-bit integer.

virtual unsigned int unsigned32BitValue() const;
Return Value

Returns the OSNumber object's integer value cast as an unsigned 32-bit integer.

Discussion

This function merely casts the internal integer value, giving no indication of truncation or other potential conversion problems.

unsigned64BitValue

Returns the OSNumber object's integer value cast as an unsigned 64-bit integer.

virtual unsigned long long unsigned64BitValue() const;
Return Value

Returns the OSNumber object's integer value cast as an unsigned 64-bit integer.

Discussion

This function merely casts the internal integer value, giving no indication of truncation or other potential conversion problems.

unsigned8BitValue

Returns the OSNumber object's integer value cast as an unsigned 8-bit integer.

virtual unsigned char unsigned8BitValue() const;
Return Value

The OSNumber object's integer value cast as an unsigned 8-bit integer.

Discussion

This function merely casts the internal integer value, giving no indication of truncation or other potential conversion problems.

withNumber(const char *, unsigned int)

Creates and initializes an instance of OSNumber with an unsigned integer value represented as a C string.

static OSNumber * withNumber( const char *valueString, unsigned int numberOfBits);
Parameters
valueString

A C string representing a numeric value for the OSNumber to store.

numberOfBits

The number of bits to limit storage to.

Return Value

An instance of OSNumber with a reference count of 1; NULL on failure.

Discussion

This function does not work in I/O Kit versions prior to 8.0 (Mac OS X 10.4). In I/O Kit version 8.0 and later, it works but is limited to parsing unsigned 32 bit quantities. The format of the C string may be decimal, hexadecimal ("0x" prefix), binary ("0b" prefix), or octal ("0" prefix).

The parsed value is masked to the provided numberOfBits when the OSNumber object is initialized.

You can change the value of an OSNumber later using setValue and addValue, but you can't change the bit size.

withNumber(unsigned long long, unsigned int)

Creates and initializes an instance of OSNumber with an integer value.

static OSNumber * withNumber( unsigned long long value, unsigned int numberOfBits);
Parameters
value

The numeric integer value for the OSNumber to store.

numberOfBits

The number of bits to limit storage to.

Return Value

An instance of OSNumber with a reference count of 1; NULL on failure.

Discussion

value is masked to the provided numberOfBits when the OSNumber object is initialized.

You can change the value of an OSNumber later using setValue and addValue, but you can't change the bit size.