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