OSString

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

Overview

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

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.

Tasks

Miscellaneous

Instance Methods

free

Deallocates or releases any resources used by the OSString instance.

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.

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.

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.

virtual unsigned int getLength() const;
Return Value

The number of characters in the OSString object.

initWithCString

Initializes an OSString from a C string.

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.

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.

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.

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.

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 <'u', 's', 'b', '\0'> or <'u', 's', 'b'> will compare as equal to the OSString containing "usb".

isEqualTo(const OSMetaClassBase *)

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

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.

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.

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.

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.

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.

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.

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.