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