Ignore:
Timestamp:
Jul 12, 2006, 1:12:08 AM (19 years ago)
Author:
ggaren
Message:

Reviewed by Maciej.


  • Implemented a vast number of renames and comment clarifications suggested during API review.


JSInternalString -> JSString
JS*Make -> JSValueMake*, JSObjectMake*
JSTypeCode -> JSType
JSValueIsInstanceOf -> JSValueIsInstanceOfConstructor (reads strangely well in client code)
JSGC*Protect -> JSValue*Protect
JS*Callback -> JSObject*Callback
JSGetPropertyListCallback -> JSObjectAddPropertiesToListCallback
JSPropertyEnumeratorGetNext -> JSPropertyEnumeratorGetNextName
JSString* ->

JSStringCreateWithUTF8CString, JSStringGetUTF8CString,
JSStringGetMaximumUTF8CStringSize JSStringIsEqualToUTF8CString,
JSStringCreateWithCFString, JSStringCopyCFString, JSStringCreateWithCharacters.


  • Changed functions taking a JSValue out arg and returning a bool indicating whether it was set to simply return a JSValue or NULL.


  • Removed JSStringGetCharacters because it's more documentation than code, and it's just a glorified memcpy built on existing API functionality.


  • Moved standard library includes into the headers that actually require them.


  • Standardized use of the phrase "Create Rule."


  • Removed JSLock from make functions that don't allocate.


  • Added exception handling to JSValueToBoolean, since we now allow callback objects to throw exceptions upon converting to boolean.


  • Renamed JSGCCollect to JSGarbageCollect.
File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/JavaScriptCore/API/JSInternalStringRef.h

    r15328 r15376  
    2929
    3030#include <JavaScriptCore/JSValueRef.h>
     31
     32#include <stdbool.h>
     33#include <stddef.h> // for size_t
     34
    3135#ifdef __cplusplus
    3236extern "C" {
    … …  
    4650@function
    4751@abstract         Creates a JavaScript string from a buffer of Unicode characters.
    48 @param chars      The buffer of Unicode characters to copy into the new JSInternalString.
     52@param chars      The buffer of Unicode characters to copy into the new JSString.
    4953@param numChars   The number of characters to copy from the buffer pointed to by chars.
    50 @result           A JSInternalString containing chars. Ownership follows the create rule.
     54@result           A JSString containing chars. Ownership follows the Create Rule.
    5155*/
    52 JSInternalStringRef JSInternalStringCreate(const JSChar* chars, size_t numChars);
     56JSStringRef JSStringCreateWithCharacters(const JSChar* chars, size_t numChars);
    5357/*!
    5458@function
    5559@abstract         Creates a JavaScript string from a null-terminated UTF8 string.
    56 @param string     The null-terminated UTF8 string to copy into the new JSInternalString.
    57 @result           A JSInternalString containing string. Ownership follows the create rule.
     60@param string     The null-terminated UTF8 string to copy into the new JSString.
     61@result           A JSString containing string. Ownership follows the Create Rule.
    5862*/
    59 JSInternalStringRef JSInternalStringCreateUTF8(const char* string);
     63JSStringRef JSStringCreateWithUTF8CString(const char* string);
    6064
    6165/*!
    6266@function
    6367@abstract         Retains a JavaScript string.
    64 @param string     The JSInternalString to retain.
    65 @result           A JSInternalString that is the same as buffer.
     68@param string     The JSString to retain.
     69@result           A JSString that is the same as string.
    6670*/
    67 JSInternalStringRef JSInternalStringRetain(JSInternalStringRef string);
     71JSStringRef JSStringRetain(JSStringRef string);
    6872/*!
    6973@function
    7074@abstract         Releases a JavaScript string.
    71 @param string     The JSInternalString to release.
     75@param string     The JSString to release.
    7276*/
    73 void JSInternalStringRelease(JSInternalStringRef string);
     77void JSStringRelease(JSStringRef string);
    7478
    7579/*!
    7680@function
    7781@abstract         Returns the number of Unicode characters in a JavaScript string.
    78 @param string     The JSInternalString whose length (in Unicode characters) you want to know.
     82@param string     The JSString whose length (in Unicode characters) you want to know.
    7983@result           The number of Unicode characters stored in string.
    8084*/
    81 size_t JSInternalStringGetLength(JSInternalStringRef string);
     85size_t JSStringGetLength(JSStringRef string);
    8286/*!
    8387@function
    84 @abstract         Quickly obtains a pointer to the Unicode character buffer that
     88@abstract         Returns a pointer to the Unicode character buffer that
    8589 serves as the backing store for a JavaScript string.
    86 @param string     The JSInternalString whose backing store you want to access.
     90@param string     The JSString whose backing store you want to access.
    8791@result           A pointer to the Unicode character buffer that serves as string's
    8892 backing store, which will be deallocated when string is deallocated.
    8993*/
    90 const JSChar* JSInternalStringGetCharactersPtr(JSInternalStringRef string);
    91 /*!
    92 @function
    93 @abstract         Copies a JavaScript string's Unicode characters into an
    94  external character buffer.
    95 @param string   The source JSInternalString.
    96 @param buffer  The destination JSChar buffer into which to copy string's
    97  characters. On return, buffer contains the requested Unicode characters.
    98 @param numChars   The number of Unicode characters to copy. This number must not
    99  exceed the length of the string.
    100 */
    101 void JSInternalStringGetCharacters(JSInternalStringRef string, JSChar* buffer, size_t numChars);
     94const JSChar* JSStringGetCharactersPtr(JSStringRef string);
    10295
    10396/*!
    10497@function
    105 @abstract         Returns the maximum number of bytes required to encode the
    106  contents of a JavaScript string as a null-terminated UTF8 string.
    107 @param string     The JSInternalString whose maximum encoded length (in bytes) you
     98@abstract Returns the maximum number of bytes a JavaScript string will
     99 take up if converted into a null-terminated UTF8 string.
     100@param string The JSString whose maximum converted size (in bytes) you
    108101 want to know.
    109 @result           The maximum number of bytes required to encode string's contents
    110  as a null-terminated UTF8 string.
     102@result The maximum number of bytes that could be required to convert string into a
     103 null-terminated UTF8 string. The number of bytes that the conversion actually ends
     104 up requiring could be less than this, but never more.
    111105*/
    112 size_t JSInternalStringGetMaxLengthUTF8(JSInternalStringRef string);
     106size_t JSStringGetMaximumUTF8CStringSize(JSStringRef string);
    113107/*!
    114108@function
    115 @abstract         Converts a JavaScript string's contents into a
    116  null-terminated UTF8 string, and copies the result into an external byte buffer.
    117 @param string   The source JSInternalString.
    118 @param buffer  The destination byte buffer into which to copy a UTF8 string
    119  representation of string. The buffer must be at least bufferSize bytes in length.
    120  On return, buffer contains a UTF8 string representation of string.
     109@abstract Converts a JavaScript string into a null-terminated UTF8 string,
     110 and copies the result into an external byte buffer.
     111@param string The source JSString.
     112@param buffer The destination byte buffer into which to copy a null-terminated
     113 UTF8 string representation of string. The buffer must be at least bufferSize
     114 bytes in size. On return, buffer contains a UTF8 string representation of string.
    121115 If bufferSize is too small, buffer will contain only partial results.
    122 @param bufferSize The length of the external buffer in bytes.
    123 @result           The number of bytes written into buffer (including the null-terminator byte).
     116@param bufferSize The size of the external buffer in bytes.
     117@result The number of bytes written into buffer (including the null-terminator byte).
    124118*/
    125 size_t JSInternalStringGetCharactersUTF8(JSInternalStringRef string, char* buffer, size_t bufferSize);
     119size_t JSStringGetUTF8CString(JSStringRef string, char* buffer, size_t bufferSize);
    126120
    127121/*!
    128122@function
    129 @abstract     Tests whether the characters in two JavaScript strings match.
    130 @param a      The first JSInternalString to test.
    131 @param b      The second JSInternalString to test.
    132 @result       true if the characters in the two strings match, otherwise false.
     123@abstract     Tests whether two JavaScript strings match.
     124@param a      The first JSString to test.
     125@param b      The second JSString to test.
     126@result       true if the two strings match, otherwise false.
    133127*/
    134 bool JSInternalStringIsEqual(JSInternalStringRef a, JSInternalStringRef b);
     128bool JSStringIsEqual(JSStringRef a, JSStringRef b);
    135129/*!
    136130@function
    137 @abstract     Tests whether the characters in a JavaScript string match
    138  the characters in a null-terminated UTF8 string.
    139 @param a      The JSInternalString to test.
     131@abstract     Tests whether a JavaScript string matches a null-terminated UTF8 string.
     132@param a      The JSString to test.
    140133@param b      The null-terminated UTF8 string to test.
    141 @result       true if the characters in the two strings match, otherwise false.
     134@result       true if the two strings match, otherwise false.
    142135*/
    143 bool JSInternalStringIsEqualUTF8(JSInternalStringRef a, const char* b);
     136bool JSStringIsEqualToUTF8CString(JSStringRef a, const char* b);
    144137
    145138#if defined(__APPLE__)
    … …  
    151144@discussion       This function is optimized to take advantage of cases when
    152145 CFStringGetCharactersPtr returns a valid pointer.
    153 @param string     The CFString to copy into the new JSInternalString.
    154 @result           A JSInternalString containing string. Ownership follows the create rule.
     146@param string     The CFString to copy into the new JSString.
     147@result           A JSString containing string. Ownership follows the Create Rule.
    155148*/
    156 JSInternalStringRef JSInternalStringCreateCF(CFStringRef string);
     149JSStringRef JSStringCreateWithCFString(CFStringRef string);
    157150/*!
    158151@function
    159152@abstract         Creates a CFString form a JavaScript string.
    160153@param alloc      The alloc parameter to pass to CFStringCreate.
    161 @param string     The JSInternalString to copy into the new CFString.
    162 @result           A CFString containing string. Ownership follows the create rule.
     154@param string     The JSString to copy into the new CFString.
     155@result           A CFString containing string. Ownership follows the Create Rule.
    163156*/
    164 CFStringRef CFStringCreateWithJSInternalString(CFAllocatorRef alloc, JSInternalStringRef string);
     157CFStringRef JSStringCopyCFString(CFAllocatorRef alloc, JSStringRef string);
    165158#endif // __APPLE__
    166159   
Note: See TracChangeset for help on using the changeset viewer.