1 /* 2 * Copyright (C) 2006 Apple Computer, Inc. All rights reserved. 3 * 4 * Redistribution and use in source and binary forms, with or without 5 * modification, are permitted provided that the following conditions 6 * are met: 7 * 1. Redistributions of source code must retain the above copyright 8 * notice, this list of conditions and the following disclaimer. 9 * 2. Redistributions in binary form must reproduce the above copyright 10 * notice, this list of conditions and the following disclaimer in the 11 * documentation and/or other materials provided with the distribution. 12 * 13 * THIS SOFTWARE IS PROVIDED BY APPLE COMPUTER, INC. ``AS IS'' AND ANY 14 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 16 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE COMPUTER, INC. OR 17 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 18 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 19 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 20 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY 21 * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 22 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 23 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 24 */ 25 26 #ifndef JSStringRef_h 27 #define JSStringRef_h 28 29 #include <JavaScriptCore/JSValueRef.h> 30 31 #ifndef __cplusplus 32 #include <stdbool.h> 33 #endif 34 #include <stddef.h> /* for size_t */ 35 36 #ifdef __cplusplus 37 extern "C" { 38 #endif 39 40 #if !defined(WIN32) && !defined(_WIN32) && !defined(__WINSCW__) \ 41 && !(defined(__CC_ARM) || defined(__ARMCC__)) /* RVCT */ 42 /*! 43 @typedef JSChar 44 @abstract A Unicode character. 45 */ 46 typedef unsigned short JSChar; 47 #else 48 typedef wchar_t JSChar; 49 #endif 50 51 /*! 52 @function 53 @abstract Creates a JavaScript string from a buffer of Unicode characters. 54 @param chars The buffer of Unicode characters to copy into the new JSString. 55 @param numChars The number of characters to copy from the buffer pointed to by chars. 56 @result A JSString containing chars. Ownership follows the Create Rule. 57 */ 58 JS_EXPORT JSStringRef JSStringCreateWithCharacters(const JSChar* chars, size_t numChars); 59 /*! 60 @function 61 @abstract Creates a JavaScript string from a null-terminated UTF8 string. 62 @param string The null-terminated UTF8 string to copy into the new JSString. 63 @result A JSString containing string. Ownership follows the Create Rule. 64 */ 65 JS_EXPORT JSStringRef JSStringCreateWithUTF8CString(const char* string); 66 67 /*! 68 @function 69 @abstract Retains a JavaScript string. 70 @param string The JSString to retain. 71 @result A JSString that is the same as string. 72 */ 73 JS_EXPORT JSStringRef JSStringRetain(JSStringRef string); 74 /*! 75 @function 76 @abstract Releases a JavaScript string. 77 @param string The JSString to release. 78 */ 79 JS_EXPORT void JSStringRelease(JSStringRef string); 80 81 /*! 82 @function 83 @abstract Returns the number of Unicode characters in a JavaScript string. 84 @param string The JSString whose length (in Unicode characters) you want to know. 85 @result The number of Unicode characters stored in string. 86 */ 87 JS_EXPORT size_t JSStringGetLength(JSStringRef string); 88 /*! 89 @function 90 @abstract Returns a pointer to the Unicode character buffer that 91 serves as the backing store for a JavaScript string. 92 @param string The JSString whose backing store you want to access. 93 @result A pointer to the Unicode character buffer that serves as string's 94 backing store, which will be deallocated when string is deallocated. 95 */ 96 JS_EXPORT const JSChar* JSStringGetCharactersPtr(JSStringRef string); 97 98 /*! 99 @function 100 @abstract Returns the maximum number of bytes a JavaScript string will 101 take up if converted into a null-terminated UTF8 string. 102 @param string The JSString whose maximum converted size (in bytes) you 103 want to know. 104 @result The maximum number of bytes that could be required to convert string into a 105 null-terminated UTF8 string. The number of bytes that the conversion actually ends 106 up requiring could be less than this, but never more. 107 */ 108 JS_EXPORT size_t JSStringGetMaximumUTF8CStringSize(JSStringRef string); 109 /*! 110 @function 111 @abstract Converts a JavaScript string into a null-terminated UTF8 string, 112 and copies the result into an external byte buffer. 113 @param string The source JSString. 114 @param buffer The destination byte buffer into which to copy a null-terminated 115 UTF8 representation of string. On return, buffer contains a UTF8 string 116 representation of string. If bufferSize is too small, buffer will contain only 117 partial results. If buffer is not at least bufferSize bytes in size, 118 behavior is undefined. 119 @param bufferSize The size of the external buffer in bytes. 120 @result The number of bytes written into buffer (including the null-terminator byte). 121 */ 122 JS_EXPORT size_t JSStringGetUTF8CString(JSStringRef string, char* buffer, size_t bufferSize); 123 124 /*! 125 @function 126 @abstract Tests whether two JavaScript strings match. 127 @param a The first JSString to test. 128 @param b The second JSString to test. 129 @result true if the two strings match, otherwise false. 130 */ 131 JS_EXPORT bool JSStringIsEqual(JSStringRef a, JSStringRef b); 132 /*! 133 @function 134 @abstract Tests whether a JavaScript string matches a null-terminated UTF8 string. 135 @param a The JSString to test. 136 @param b The null-terminated UTF8 string to test. 137 @result true if the two strings match, otherwise false. 138 */ 139 JS_EXPORT bool JSStringIsEqualToUTF8CString(JSStringRef a, const char* b); 140 141 #ifdef __cplusplus 142 } 143 #endif 144 145 #endif /* JSStringRef_h */ 146