OSNumber

Overview

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

Discussion

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.

Functions

addValue

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

free

Deallocates or releases any resources used by the OSNumber instance.

init(const char *, unsigned int)

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

init(unsigned long long, unsigned int)

Initializes an instance of OSNumber with an integer value.

isEqualTo(const OSMetaClassBase *)

Tests the equality an OSNumber to an arbitrary object.

isEqualTo(const OSNumber *)

Tests the equality of two OSNumber objects.

numberOfBits

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

numberOfBytes

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

serialize

Archives the receiver into the provided OSSerialize object.

setValue

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

unsigned16BitValue

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

unsigned32BitValue

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

unsigned64BitValue

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

unsigned8BitValue

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

withNumber(const char *, unsigned int)

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

withNumber(unsigned long long, unsigned int)

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

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

public

virtual void addValue(
    signed long long value); 

Parameters

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.

Deallocates or releases any resources used by the OSNumber instance.

public

virtual void free(); 

Discussion

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

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

public

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

Parameters

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.

Initializes an instance of OSNumber with an integer value.

public

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

Parameters

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.

Tests the equality an OSNumber to an arbitrary object.

public

virtual bool isEqualTo(
    const OSMetaClassBase * anObject) const; 

Parameters

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.

Tests the equality of two OSNumber objects.

public

virtual bool isEqualTo(
    const OSNumber * aNumber) const; 

Parameters

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.

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

public

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.

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

public

virtual unsigned int numberOfBytes() const; 

Return Value

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

Archives the receiver into the provided OSSerialize object.

public

virtual bool serialize(
    OSSerialize *serializer) const; 

Parameters

Return Value

true if serialization succeeds, false if not.

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

public

virtual void setValue(
    unsigned long long value); 

Parameters

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

public

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.

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

public

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.

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

public

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.

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

public

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.

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

public

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

Parameters

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.

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

public

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

Parameters

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.

Last Updated: 2009-10-14