objc2_javascript_core/generated/JSStringRef.rs
1//! This file has been automatically generated by `objc2`'s `header-translator`.
2//! DO NOT EDIT
3use core::ffi::*;
4
5use crate::*;
6
7/// A UTF-16 code unit. One, or a sequence of two, can encode any Unicode
8/// character. As with all scalar types, endianness depends on the underlying
9/// architecture.
10///
11/// See also [Apple's documentation](https://developer.apple.com/documentation/javascriptcore/jschar?language=objc)
12pub type JSChar = c_ushort;
13
14extern "C-unwind" {
15 /// Creates a JavaScript string from a buffer of Unicode characters.
16 ///
17 /// Parameter `chars`: The buffer of Unicode characters to copy into the new JSString.
18 ///
19 /// Parameter `numChars`: The number of characters to copy from the buffer pointed to by chars.
20 ///
21 /// Returns: A JSString containing chars. Ownership follows the Create Rule.
22 ///
23 /// # Safety
24 ///
25 /// `chars` must be a valid pointer.
26 #[cfg(feature = "JSBase")]
27 pub fn JSStringCreateWithCharacters(chars: *const JSChar, num_chars: usize) -> JSStringRef;
28}
29
30extern "C-unwind" {
31 /// Creates a JavaScript string from a null-terminated UTF8 string.
32 ///
33 /// Parameter `string`: The null-terminated UTF8 string to copy into the new JSString.
34 ///
35 /// Returns: A JSString containing string. Ownership follows the Create Rule.
36 ///
37 /// # Safety
38 ///
39 /// `string` must be a valid pointer.
40 #[cfg(feature = "JSBase")]
41 pub fn JSStringCreateWithUTF8CString(string: *const c_char) -> JSStringRef;
42}
43
44extern "C-unwind" {
45 /// Retains a JavaScript string.
46 ///
47 /// Parameter `string`: The JSString to retain.
48 ///
49 /// Returns: A JSString that is the same as string.
50 ///
51 /// # Safety
52 ///
53 /// `string` must be a valid pointer.
54 #[cfg(feature = "JSBase")]
55 pub fn JSStringRetain(string: JSStringRef) -> JSStringRef;
56}
57
58extern "C-unwind" {
59 /// Releases a JavaScript string.
60 ///
61 /// Parameter `string`: The JSString to release.
62 ///
63 /// # Safety
64 ///
65 /// `string` must be a valid pointer.
66 #[cfg(feature = "JSBase")]
67 pub fn JSStringRelease(string: JSStringRef);
68}
69
70extern "C-unwind" {
71 /// Returns the number of Unicode characters in a JavaScript string.
72 ///
73 /// Parameter `string`: The JSString whose length (in Unicode characters) you want to know.
74 ///
75 /// Returns: The number of Unicode characters stored in string.
76 ///
77 /// # Safety
78 ///
79 /// `string` must be a valid pointer.
80 #[cfg(feature = "JSBase")]
81 pub fn JSStringGetLength(string: JSStringRef) -> usize;
82}
83
84extern "C-unwind" {
85 /// Returns a pointer to the Unicode character buffer that
86 /// serves as the backing store for a JavaScript string.
87 ///
88 /// Parameter `string`: The JSString whose backing store you want to access.
89 ///
90 /// Returns: A pointer to the Unicode character buffer that serves as string's
91 /// backing store, which will be deallocated when string is deallocated.
92 ///
93 /// # Safety
94 ///
95 /// `string` must be a valid pointer.
96 #[cfg(feature = "JSBase")]
97 pub fn JSStringGetCharactersPtr(string: JSStringRef) -> *const JSChar;
98}
99
100extern "C-unwind" {
101 /// Returns the maximum number of bytes a JavaScript string will
102 /// take up if converted into a null-terminated UTF8 string.
103 ///
104 /// Parameter `string`: The JSString whose maximum converted size (in bytes) you
105 /// want to know.
106 ///
107 /// Returns: The maximum number of bytes that could be required to convert string into a
108 /// null-terminated UTF8 string. The number of bytes that the conversion actually ends
109 /// up requiring could be less than this, but never more.
110 ///
111 /// # Safety
112 ///
113 /// `string` must be a valid pointer.
114 #[cfg(feature = "JSBase")]
115 pub fn JSStringGetMaximumUTF8CStringSize(string: JSStringRef) -> usize;
116}
117
118extern "C-unwind" {
119 /// Converts a JavaScript string into a null-terminated UTF8 string,
120 /// and copies the result into an external byte buffer.
121 ///
122 /// Parameter `string`: The source JSString.
123 ///
124 /// Parameter `buffer`: The destination byte buffer into which to copy a null-terminated
125 /// UTF8 representation of string. On return, buffer contains a UTF8 string
126 /// representation of string. If bufferSize is too small, buffer will contain only
127 /// partial results. If buffer is not at least bufferSize bytes in size,
128 /// behavior is undefined.
129 ///
130 /// Parameter `bufferSize`: The size of the external buffer in bytes.
131 ///
132 /// Returns: The number of bytes written into buffer (including the null-terminator byte).
133 ///
134 /// # Safety
135 ///
136 /// - `string` must be a valid pointer.
137 /// - `buffer` must be a valid pointer.
138 #[cfg(feature = "JSBase")]
139 pub fn JSStringGetUTF8CString(
140 string: JSStringRef,
141 buffer: *mut c_char,
142 buffer_size: usize,
143 ) -> usize;
144}
145
146extern "C-unwind" {
147 /// Tests whether two JavaScript strings match.
148 ///
149 /// Parameter `a`: The first JSString to test.
150 ///
151 /// Parameter `b`: The second JSString to test.
152 ///
153 /// Returns: true if the two strings match, otherwise false.
154 ///
155 /// # Safety
156 ///
157 /// - `a` must be a valid pointer.
158 /// - `b` must be a valid pointer.
159 #[cfg(feature = "JSBase")]
160 pub fn JSStringIsEqual(a: JSStringRef, b: JSStringRef) -> bool;
161}
162
163extern "C-unwind" {
164 /// Tests whether a JavaScript string matches a null-terminated UTF8 string.
165 ///
166 /// Parameter `a`: The JSString to test.
167 ///
168 /// Parameter `b`: The null-terminated UTF8 string to test.
169 ///
170 /// Returns: true if the two strings match, otherwise false.
171 ///
172 /// # Safety
173 ///
174 /// - `a` must be a valid pointer.
175 /// - `b` must be a valid pointer.
176 #[cfg(feature = "JSBase")]
177 pub fn JSStringIsEqualToUTF8CString(a: JSStringRef, b: *const c_char) -> bool;
178}