OSString

Inherits from:	OSObject
Declared In:	OSString.h

Overview

OSString wraps a C string in a C++ object for use in Libkern collections.

Discussion

OSString is a container class for managing arrays of characters. An OSString normally maintains its own character buffer and allows changes, but you can create an "immutable" OSString that references an external C string buffer using the "NoCopy" creator functions. Functions called to change the contents of an immutable OSString will fail.

Encodings

OSString makes no provisions for different character encodings and assumes that a string is a nul-terminated sequence of single-byte characters. User-space code must either assume an encoding (typically ASCII or UTF-8) or determine it in some other way (such as an IORegistryEntry property).

Altering Strings

OSString's indended use is as a reference-counted object container for a C string and little more. While OSString provides full access to the underlying C string, it provides little in the way of string object manipulation; there are no append or insert functions, only a set-character function. If you need to manipulate OSStrings, it's generally best to get the C strings, alter them as necessary, and create a new OSString object from the resulting C string.

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.

OSString 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

free: Deallocates or releases any resources used by the OSString instance.
getChar: Returns the character at a given index in the string object.
getCStringNoCopy: Returns a pointer to the internal C string buffer.
getLength: Returns the number of characters in the OSString object.
initWithCString: Initializes an OSString from a C string.
initWithCStringNoCopy: Initializes an immutable OSString to share the provided C string buffer.
initWithString: Initializes an OSString from another OSString.
isEqualTo(const char *): Tests the equality of an OSString object with a C string.
isEqualTo(const OSData *): Tests the equality of an OSData object and the OSString instance.
isEqualTo(const OSMetaClassBase *): Tests the equality of an OSString object to an arbitrary object.
isEqualTo(const OSString *): Tests the equality of two OSString objects.
serialize: Archives the receiver into the provided OSSerialize object.
setChar: Replaces a character at a given index in the string object.
withCString: Creates and initializes an OSString from a C string.
withCStringNoCopy: Creates and initializes an immutable OSString that shares the provided C string buffer.
withString: Creates and initializes an OSString from another OSString.

free

Deallocates or releases any resources used by the OSString instance.

public

virtual void free();

Discussion

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

getChar

Returns the character at a given index in the string object.

public

virtual char getChar(
    unsigned int index) const;

Parameters

index: The index into the string.

Return Value

The character at index within the string, or '\0' if index is past the end of the string.

getCStringNoCopy

Returns a pointer to the internal C string buffer.

public

virtual const char * getCStringNoCopy() const;

Return Value

A pointer to the internal C string buffer.

getLength

Returns the number of characters in the OSString object.

public

virtual unsigned int getLength() const;

Return Value

The number of characters in the OSString object.

initWithCString

Initializes an OSString from a C string.

public

virtual bool initWithCString(
    const char *cString);

Parameters

cString: The C string to copy into the new OSString.

Return Value

true on success, false on failure.

Discussion

Not for general use. Use the static instance creation method withCString instead.

initWithCStringNoCopy

Initializes an immutable OSString to share the provided C string buffer.

public

virtual bool initWithCStringNoCopy(
    const char *cString);

Parameters

cString: The C string to reference.

Return Value

true on success, false on failure.

Discussion

Not for general use. Use the static instance creation method withCStringNoCopy instead.

An OSString object initialized with this function does not claim ownership of the C string, but shares it with the caller. When the caller determines that the OSString object has actually been freed, it can safely dispose of the data buffer. Conversely, if it frees the shared data buffer, it must not attempt to use the OSString object and should release it.

An OSString object created with this function does not allow changing the string via setChar.

initWithString

Initializes an OSString from another OSString.

public

virtual bool initWithString(
    const OSString *aString);

Parameters

aString: The OSString object whose contents to copy.

Return Value

true on success, false on failure.

Discussion

Not for general use. Use the static instance creation method withString instead.

isEqualTo(const char *)

Tests the equality of an OSString object with a C string.

public

virtual bool isEqualTo(
    const char *cString) const;

Parameters

cString: The C string to compare against the receiver.

Return Value

true if the OSString's characters are equivalent to the C string's, false otherwise.

isEqualTo(const OSData *)

Tests the equality of an OSData object and the OSString instance.

public

virtual bool isEqualTo(
    const OSData *aDataObject) const;

Parameters

aDataObject: An OSData object.

Return Value

true if the two objects are equivalent, false otherwise.

Discussion

This function compares the bytes of the OSData object against those of the OSString, accounting for the possibility that an OSData might explicitly include a nul character as part of its total length. Thus, for example, an OSData object containing either the bytes or will compare as equal to the OSString containing "usb".

isEqualTo(const OSMetaClassBase *)

Tests the equality of an OSString object to an arbitrary object.

public

virtual bool isEqualTo(
    const OSMetaClassBase *anObject) const;

Parameters

anObject: The object to be compared against the receiver.

Return Value

Returns true if the two objects are equivalent, false otherwise.

Discussion

An OSString is considered equal to another object if that object is derived from OSString and contains the equivalent bytes of the same length.

isEqualTo(const OSString *)

Tests the equality of two OSString objects.

public

virtual bool isEqualTo(
    const OSString *aString) const;

Parameters

aString: The OSString object being compared against the receiver.

Return Value

true if the two OSString objects are equivalent, false otherwise.

Discussion

Two OSString objects are considered equal if they have same length and if their byte buffers hold the same contents.

serialize

Archives the receiver into the provided OSSerialize object.

public

virtual bool serialize(
    OSSerialize *serializer) const;

Parameters

serializer: The OSSerialize object.

Return Value

true if serialization succeeds, false if not.

setChar

Replaces a character at a given index in the string object.

public

virtual bool setChar(
    char aChar,
    unsigned int index);

Parameters

aChar: The character value to set.
index: The index into the string.

Return Value

true if the character was replaced, false if the was created "NoCopy" or index is past the end of the string.

withCString

Creates and initializes an OSString from a C string.

public

static OSString * withCString(
    const char *cString);

Parameters

cString: The C string to copy into the new OSString.

Return Value

An instance of OSString representing the same characters as aString, and with a reference count of 1; NULL on failure.

withCStringNoCopy

Creates and initializes an immutable OSString that shares the provided C string buffer.

public

static OSString * withCStringNoCopy(
    const char *cString);

Parameters

cString: The C string to reference.

Return Value

An instance of OSString containing cString, and with a reference count of 1; NULL on failure.

Discussion

An OSString object created with this function does not claim ownership of the C string, but shares it with the caller. When the caller determines that the OSString object has actually been freed, it can safely dispose of the data buffer. Conversely, if it frees the shared data buffer, it must not attempt to use the OSString object and should release it.

An OSString object created with this function does not allow changing the string via setChar.

withString

Creates and initializes an OSString from another OSString.

public

static OSString * withString(
    const OSString *aString);

Parameters

aString: The OSString object whose contents to copy.

Return Value

An instance of OSString representing the same characters as aString, and with a reference count of 1; NULL on failure.

Discussion

The new OSString is a distinct instance from aString, and is not merely the original object with the reference count incremented. Changes to one will not be reflected in the other.

Mac Dev Center Mac OS X Reference Library Drivers, Kernel, & Hardware: Kernel Device Drivers Kernel Framework Reference

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.

Last Updated: 2010-07-29