ADC Home > Reference Library > Reference > Carbon > Internet & Web > JavaScriptCore Framework Reference

JSStringRef.h

Includes:

Overview

Functions

JSStringCreateWithCharacters: Creates a JavaScript string from a buffer of Unicode characters.
JSStringCreateWithUTF8CString: Creates a JavaScript string from a null-terminated UTF8 string.
JSStringGetCharactersPtr: Returns a pointer to the Unicode character buffer that serves as the backing store for a JavaScript string.
JSStringGetLength: Returns the number of Unicode characters in a JavaScript string.
JSStringGetMaximumUTF8CStringSize: Returns the maximum number of bytes a JavaScript string will take up if converted into a null-terminated UTF8 string.
JSStringGetUTF8CString: Converts a JavaScript string into a null-terminated UTF8 string, and copies the result into an external byte buffer.
JSStringIsEqual: Tests whether two JavaScript strings match.
JSStringIsEqualToUTF8CString: Tests whether a JavaScript string matches a null-terminated UTF8 string.
JSStringRelease: Releases a JavaScript string.
JSStringRetain: Retains a JavaScript string.

JSStringCreateWithCharacters

Creates a JavaScript string from a buffer of Unicode characters.

JSStringRef JSStringCreateWithCharacters(
    const JSChar *chars,
    size_t numChars);

Parameters

chars: The buffer of Unicode characters to copy into the new JSString.
numChars: The number of characters to copy from the buffer pointed to by chars.

Return Value

A JSString containing chars. Ownership follows the Create Rule.

JSStringCreateWithUTF8CString

Creates a JavaScript string from a null-terminated UTF8 string.

JSStringRef JSStringCreateWithUTF8CString(
    const char *string);

Parameters

string: The null-terminated UTF8 string to copy into the new JSString.

Return Value

A JSString containing string. Ownership follows the Create Rule.

JSStringGetCharactersPtr

Returns a pointer to the Unicode character buffer that serves as the backing store for a JavaScript string.

const JSChar* JSStringGetCharactersPtr(
    JSStringRef string);

Parameters

string: The JSString whose backing store you want to access.

Return Value

A pointer to the Unicode character buffer that serves as string's backing store, which will be deallocated when string is deallocated.

JSStringGetLength

Returns the number of Unicode characters in a JavaScript string.

size_t JSStringGetLength(
    JSStringRef string);

Parameters

string: The JSString whose length (in Unicode characters) you want to know.

Return Value

The number of Unicode characters stored in string.

JSStringGetMaximumUTF8CStringSize

Returns the maximum number of bytes a JavaScript string will take up if converted into a null-terminated UTF8 string.

size_t JSStringGetMaximumUTF8CStringSize(
    JSStringRef string);

Parameters

string: The JSString whose maximum converted size (in bytes) you want to know.

Return Value

The maximum number of bytes that could be required to convert string into a null-terminated UTF8 string. The number of bytes that the conversion actually ends up requiring could be less than this, but never more.

JSStringGetUTF8CString

Converts a JavaScript string into a null-terminated UTF8 string, and copies the result into an external byte buffer.

size_t JSStringGetUTF8CString(
    JSStringRef string,
    char *buffer,
    size_t bufferSize);

Parameters

string: The source JSString.
buffer: The destination byte buffer into which to copy a null-terminated UTF8 representation of string. On return, buffer contains a UTF8 string representation of string. If bufferSize is too small, buffer will contain only partial results. If buffer is not at least bufferSize bytes in size, behavior is undefined.
bufferSize: The size of the external buffer in bytes.

Return Value

The number of bytes written into buffer (including the null-terminator byte).

JSStringIsEqual

Tests whether two JavaScript strings match.

bool JSStringIsEqual(
    JSStringRef a,
    JSStringRef b);

Parameters

a: The first JSString to test.
b: The second JSString to test.

Return Value

true if the two strings match, otherwise false.

JSStringIsEqualToUTF8CString

Tests whether a JavaScript string matches a null-terminated UTF8 string.

bool JSStringIsEqualToUTF8CString(
    JSStringRef a,
    const char *b);

Parameters

a: The JSString to test.
b: The null-terminated UTF8 string to test.

Return Value

true if the two strings match, otherwise false.

JSStringRelease

Releases a JavaScript string.

void JSStringRelease(
    JSStringRef string);

Parameters

string: The JSString to release.

JSStringRetain

Retains a JavaScript string.

JSStringRef JSStringRetain(
    JSStringRef string);

Parameters

string: The JSString to retain.

Return Value

A JSString that is the same as string.

Typedefs

JSChar

A Unicode character.

typedef unsigned short JSChar;

Did this document help you?

Yes: Tell us what works for you.

It’s good, but: Report typos, inaccuracies, and so forth.

It wasn’t helpful: Tell us what would have helped.

Last Updated: 2008-03-11