Mac Developer Library

Developer

OSString Class Reference

Options
Deployment Target:

On This Page
Language:

OSString

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

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Not Applicable @import Kernel;

Availability


Available in OS X v10.0 and later.
  • Deallocates or releases any resources used by the OSString instance.

    Declaration

    C++

    virtual void free();

    Discussion

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

    Import Statement

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

    Declaration

    C++

    virtual char getChar( unsigned intindex) 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.

    Import Statement

  • Returns a pointer to the internal C string buffer.

    Declaration

    C++

    virtual const char * getCStringNoCopy() const;

    Return Value

    A pointer to the internal C string buffer.

    Import Statement

  • Returns the number of characters in the OSString object.

    Declaration

    C++

    virtual unsigned int getLength() const;

    Return Value

    The number of characters in the OSString object.

    Import Statement

  • Initializes an OSString from a C string.

    Declaration

    C++

    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.

    Import Statement

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

    Declaration

    C++

    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.

    Import Statement

  • Initializes an OSString from another OSString.

    Declaration

    C++

    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.

    Import Statement

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

    Declaration

    C++

    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.

    Import Statement

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

    Declaration

    C++

    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".

    Import Statement

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

    Declaration

    C++

    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.

    Import Statement

  • Tests the equality of two OSString objects.

    Declaration

    C++

    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.

    Import Statement

  • Archives the receiver into the provided OSSerialize object.

    Declaration

    C++

    virtual bool serialize( OSSerialize *serializer) const;

    Parameters

    serializer

    The OSSerialize object.

    Return Value

    true if serialization succeeds, false if not.

    Import Statement

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

    Declaration

    C++

    virtual bool setChar( charaChar, unsigned intindex);

    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.

    Import Statement

  • Creates and initializes an OSString from a C string.

    Declaration

    C++

    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.

    Import Statement

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

    Declaration

    C++

    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.

    Import Statement

  • Creates and initializes an OSString from another OSString.

    Declaration

    C++

    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.

    Import Statement