1 /*
2  * This file is part of gtkD.
3  *
4  * gtkD is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU Lesser General Public License
6  * as published by the Free Software Foundation; either version 3
7  * of the License, or (at your option) any later version, with
8  * some exceptions, please read the COPYING file.
9  *
10  * gtkD is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13  * GNU Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public License
16  * along with gtkD; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA
18  */
19 
20 // generated automatically - do not change
21 // find conversion definition on APILookup.txt
22 // implement new conversion functionalities on the wrap.utils pakage
23 
24 
25 module glib.Bytes;
26 
27 private import glib.ByteArray;
28 private import glib.ConstructionException;
29 private import gtkc.glib;
30 public  import gtkc.glibtypes;
31 
32 
33 /**
34  * A simple refcounted data type representing an immutable sequence of zero or
35  * more bytes from an unspecified origin.
36  * 
37  * The purpose of a #GBytes is to keep the memory region that it holds
38  * alive for as long as anyone holds a reference to the bytes.  When
39  * the last reference count is dropped, the memory is released. Multiple
40  * unrelated callers can use byte data in the #GBytes without coordinating
41  * their activities, resting assured that the byte data will not change or
42  * move while they hold a reference.
43  * 
44  * A #GBytes can come from many different origins that may have
45  * different procedures for freeing the memory region.  Examples are
46  * memory from g_malloc(), from memory slices, from a #GMappedFile or
47  * memory from other allocators.
48  * 
49  * #GBytes work well as keys in #GHashTable. Use g_bytes_equal() and
50  * g_bytes_hash() as parameters to g_hash_table_new() or g_hash_table_new_full().
51  * #GBytes can also be used as keys in a #GTree by passing the g_bytes_compare()
52  * function to g_tree_new().
53  * 
54  * The data pointed to by this bytes must not be modified. For a mutable
55  * array of bytes see #GByteArray. Use g_bytes_unref_to_array() to create a
56  * mutable array for a #GBytes sequence. To create an immutable #GBytes from
57  * a mutable #GByteArray, use the g_byte_array_free_to_bytes() function.
58  *
59  * Since: 2.32
60  */
61 public class Bytes
62 {
63 	/** the main Gtk struct */
64 	protected GBytes* gBytes;
65 
66 	/** Get the main Gtk struct */
67 	public GBytes* getBytesStruct()
68 	{
69 		return gBytes;
70 	}
71 
72 	/** the main Gtk struct as a void* */
73 	protected void* getStruct()
74 	{
75 		return cast(void*)gBytes;
76 	}
77 
78 	/**
79 	 * Sets our main struct and passes it to the parent class.
80 	 */
81 	public this (GBytes* gBytes)
82 	{
83 		this.gBytes = gBytes;
84 	}
85 
86 	/**
87 	 */
88 
89 	/**
90 	 * Creates a new #GBytes from @data.
91 	 *
92 	 * @data is copied. If @size is 0, @data may be %NULL.
93 	 *
94 	 * Params:
95 	 *     data = the data to be used for the bytes
96 	 *     size = the size of @data
97 	 *
98 	 * Return: a new #GBytes
99 	 *
100 	 * Since: 2.32
101 	 *
102 	 * Throws: ConstructionException GTK+ fails to create the object.
103 	 */
104 	public this(ubyte[] data)
105 	{
106 		auto p = g_bytes_new(data.ptr, cast(size_t)data.length);
107 		
108 		if(p is null)
109 		{
110 			throw new ConstructionException("null returned by new");
111 		}
112 		
113 		this(cast(GBytes*) p);
114 	}
115 
116 	/**
117 	 * Creates a #GBytes from @data.
118 	 *
119 	 * When the last reference is dropped, @free_func will be called with the
120 	 * @user_data argument.
121 	 *
122 	 * @data must not be modified after this call is made until @free_func has
123 	 * been called to indicate that the bytes is no longer in use.
124 	 *
125 	 * @data may be %NULL if @size is 0.
126 	 *
127 	 * Params:
128 	 *     data = the data to be used for the bytes
129 	 *     size = the size of @data
130 	 *     freeFunc = the function to call to release the data
131 	 *     userData = data to pass to @free_func
132 	 *
133 	 * Return: a new #GBytes
134 	 *
135 	 * Since: 2.32
136 	 *
137 	 * Throws: ConstructionException GTK+ fails to create the object.
138 	 */
139 	public this(void[] data, GDestroyNotify freeFunc, void* userData)
140 	{
141 		auto p = g_bytes_new_with_free_func(data.ptr, cast(size_t)data.length, freeFunc, userData);
142 		
143 		if(p is null)
144 		{
145 			throw new ConstructionException("null returned by new_with_free_func");
146 		}
147 		
148 		this(cast(GBytes*) p);
149 	}
150 
151 	/**
152 	 * Compares the two #GBytes values.
153 	 *
154 	 * This function can be used to sort GBytes instances in lexographical order.
155 	 *
156 	 * Params:
157 	 *     bytes2 = a pointer to a #GBytes to compare with @bytes1
158 	 *
159 	 * Return: a negative value if bytes2 is lesser, a positive value if bytes2 is
160 	 *     greater, and zero if bytes2 is equal to bytes1
161 	 *
162 	 * Since: 2.32
163 	 */
164 	public int compare(Bytes bytes2)
165 	{
166 		return g_bytes_compare(gBytes, (bytes2 is null) ? null : bytes2.getBytesStruct());
167 	}
168 
169 	/**
170 	 * Compares the two #GBytes values being pointed to and returns
171 	 * %TRUE if they are equal.
172 	 *
173 	 * This function can be passed to g_hash_table_new() as the @key_equal_func
174 	 * parameter, when using non-%NULL #GBytes pointers as keys in a #GHashTable.
175 	 *
176 	 * Params:
177 	 *     bytes2 = a pointer to a #GBytes to compare with @bytes1
178 	 *
179 	 * Return: %TRUE if the two keys match.
180 	 *
181 	 * Since: 2.32
182 	 */
183 	public bool equal(Bytes bytes2)
184 	{
185 		return g_bytes_equal(gBytes, (bytes2 is null) ? null : bytes2.getBytesStruct()) != 0;
186 	}
187 
188 	/**
189 	 * Get the byte data in the #GBytes. This data should not be modified.
190 	 *
191 	 * This function will always return the same pointer for a given #GBytes.
192 	 *
193 	 * %NULL may be returned if @size is 0. This is not guaranteed, as the #GBytes
194 	 * may represent an empty string with @data non-%NULL and @size as 0. %NULL will
195 	 * not be returned if @size is non-zero.
196 	 *
197 	 * Return: a pointer to the
198 	 *     byte data, or %NULL
199 	 *
200 	 * Since: 2.32
201 	 */
202 	public void[] getData()
203 	{
204 		size_t size;
205 		
206 		auto p = g_bytes_get_data(gBytes, &size);
207 		
208 		return p[0 .. size];
209 	}
210 
211 	/**
212 	 * Get the size of the byte data in the #GBytes.
213 	 *
214 	 * This function will always return the same value for a given #GBytes.
215 	 *
216 	 * Return: the size
217 	 *
218 	 * Since: 2.32
219 	 */
220 	public size_t getSize()
221 	{
222 		return g_bytes_get_size(gBytes);
223 	}
224 
225 	/**
226 	 * Creates an integer hash code for the byte data in the #GBytes.
227 	 *
228 	 * This function can be passed to g_hash_table_new() as the @key_hash_func
229 	 * parameter, when using non-%NULL #GBytes pointers as keys in a #GHashTable.
230 	 *
231 	 * Return: a hash value corresponding to the key.
232 	 *
233 	 * Since: 2.32
234 	 */
235 	public uint hash()
236 	{
237 		return g_bytes_hash(gBytes);
238 	}
239 
240 	/**
241 	 * Creates a #GBytes which is a subsection of another #GBytes. The @offset +
242 	 * @length may not be longer than the size of @bytes.
243 	 *
244 	 * A reference to @bytes will be held by the newly created #GBytes until
245 	 * the byte data is no longer needed.
246 	 *
247 	 * Params:
248 	 *     offset = offset which subsection starts at
249 	 *     length = length of subsection
250 	 *
251 	 * Return: a new #GBytes
252 	 *
253 	 * Since: 2.32
254 	 */
255 	public Bytes newFromBytes(size_t offset, size_t length)
256 	{
257 		auto p = g_bytes_new_from_bytes(gBytes, offset, length);
258 		
259 		if(p is null)
260 		{
261 			return null;
262 		}
263 		
264 		return new Bytes(cast(GBytes*) p);
265 	}
266 
267 	/**
268 	 * Increase the reference count on @bytes.
269 	 *
270 	 * Return: the #GBytes
271 	 *
272 	 * Since: 2.32
273 	 */
274 	public Bytes doref()
275 	{
276 		auto p = g_bytes_ref(gBytes);
277 		
278 		if(p is null)
279 		{
280 			return null;
281 		}
282 		
283 		return new Bytes(cast(GBytes*) p);
284 	}
285 
286 	/**
287 	 * Releases a reference on @bytes.  This may result in the bytes being
288 	 * freed.
289 	 *
290 	 * Since: 2.32
291 	 */
292 	public void unref()
293 	{
294 		g_bytes_unref(gBytes);
295 	}
296 
297 	/**
298 	 * Unreferences the bytes, and returns a new mutable #GByteArray containing
299 	 * the same byte data.
300 	 *
301 	 * As an optimization, the byte data is transferred to the array without copying
302 	 * if this was the last reference to bytes and bytes was created with
303 	 * g_bytes_new(), g_bytes_new_take() or g_byte_array_free_to_bytes(). In all
304 	 * other cases the data is copied.
305 	 *
306 	 * Return: a new mutable #GByteArray containing the same byte data
307 	 *
308 	 * Since: 2.32
309 	 */
310 	public ByteArray unrefToArray()
311 	{
312 		auto p = g_bytes_unref_to_array(gBytes);
313 		
314 		if(p is null)
315 		{
316 			return null;
317 		}
318 		
319 		return new ByteArray(cast(GByteArray*) p);
320 	}
321 
322 	/**
323 	 * Unreferences the bytes, and returns a pointer the same byte data
324 	 * contents.
325 	 *
326 	 * As an optimization, the byte data is returned without copying if this was
327 	 * the last reference to bytes and bytes was created with g_bytes_new(),
328 	 * g_bytes_new_take() or g_byte_array_free_to_bytes(). In all other cases the
329 	 * data is copied.
330 	 *
331 	 * Params:
332 	 *     size = location to place the length of the returned data
333 	 *
334 	 * Return: a pointer to the same byte data, which should
335 	 *     be freed with g_free()
336 	 *
337 	 * Since: 2.32
338 	 */
339 	public void* unrefToData(size_t* size)
340 	{
341 		return g_bytes_unref_to_data(gBytes, size);
342 	}
343 }