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 glib.c.functions;
30 public  import glib.c.types;
31 public  import gtkc.glibtypes;
32 private import gtkd.Loader;
33 
34 
35 /**
36  * A simple refcounted data type representing an immutable sequence of zero or
37  * more bytes from an unspecified origin.
38  * 
39  * The purpose of a #GBytes is to keep the memory region that it holds
40  * alive for as long as anyone holds a reference to the bytes.  When
41  * the last reference count is dropped, the memory is released. Multiple
42  * unrelated callers can use byte data in the #GBytes without coordinating
43  * their activities, resting assured that the byte data will not change or
44  * move while they hold a reference.
45  * 
46  * A #GBytes can come from many different origins that may have
47  * different procedures for freeing the memory region.  Examples are
48  * memory from g_malloc(), from memory slices, from a #GMappedFile or
49  * memory from other allocators.
50  * 
51  * #GBytes work well as keys in #GHashTable. Use g_bytes_equal() and
52  * g_bytes_hash() as parameters to g_hash_table_new() or g_hash_table_new_full().
53  * #GBytes can also be used as keys in a #GTree by passing the g_bytes_compare()
54  * function to g_tree_new().
55  * 
56  * The data pointed to by this bytes must not be modified. For a mutable
57  * array of bytes see #GByteArray. Use g_bytes_unref_to_array() to create a
58  * mutable array for a #GBytes sequence. To create an immutable #GBytes from
59  * a mutable #GByteArray, use the g_byte_array_free_to_bytes() function.
60  *
61  * Since: 2.32
62  */
63 public class Bytes
64 {
65 	/** the main Gtk struct */
66 	protected GBytes* gBytes;
67 	protected bool ownedRef;
68 
69 	/** Get the main Gtk struct */
70 	public GBytes* getBytesStruct(bool transferOwnership = false)
71 	{
72 		if (transferOwnership)
73 			ownedRef = false;
74 		return gBytes;
75 	}
76 
77 	/** the main Gtk struct as a void* */
78 	protected void* getStruct()
79 	{
80 		return cast(void*)gBytes;
81 	}
82 
83 	/**
84 	 * Sets our main struct and passes it to the parent class.
85 	 */
86 	public this (GBytes* gBytes, bool ownedRef = false)
87 	{
88 		this.gBytes = gBytes;
89 		this.ownedRef = ownedRef;
90 	}
91 
92 	~this ()
93 	{
94 		if ( Linker.isLoaded(LIBRARY_GLIB) && ownedRef )
95 			g_bytes_unref(gBytes);
96 	}
97 
98 
99 	/**
100 	 * Creates a new #GBytes from @data.
101 	 *
102 	 * @data is copied. If @size is 0, @data may be %NULL.
103 	 *
104 	 * Params:
105 	 *     data = the data to be used for the bytes
106 	 *
107 	 * Returns: a new #GBytes
108 	 *
109 	 * Since: 2.32
110 	 *
111 	 * Throws: ConstructionException GTK+ fails to create the object.
112 	 */
113 	public this(ubyte[] data)
114 	{
115 		auto p = g_bytes_new(data.ptr, cast(size_t)data.length);
116 
117 		if(p is null)
118 		{
119 			throw new ConstructionException("null returned by new");
120 		}
121 
122 		this(cast(GBytes*) p);
123 	}
124 
125 	/**
126 	 * Creates a #GBytes from @data.
127 	 *
128 	 * When the last reference is dropped, @free_func will be called with the
129 	 * @user_data argument.
130 	 *
131 	 * @data must not be modified after this call is made until @free_func has
132 	 * been called to indicate that the bytes is no longer in use.
133 	 *
134 	 * @data may be %NULL if @size is 0.
135 	 *
136 	 * Params:
137 	 *     data = the data to be used for the bytes
138 	 *     freeFunc = the function to call to release the data
139 	 *     userData = data to pass to @free_func
140 	 *
141 	 * Returns: a new #GBytes
142 	 *
143 	 * Since: 2.32
144 	 *
145 	 * Throws: ConstructionException GTK+ fails to create the object.
146 	 */
147 	public this(ubyte[] data, GDestroyNotify freeFunc, void* userData)
148 	{
149 		auto p = g_bytes_new_with_free_func(data.ptr, cast(size_t)data.length, freeFunc, userData);
150 
151 		if(p is null)
152 		{
153 			throw new ConstructionException("null returned by new_with_free_func");
154 		}
155 
156 		this(cast(GBytes*) p);
157 	}
158 
159 	/**
160 	 * Compares the two #GBytes values.
161 	 *
162 	 * This function can be used to sort GBytes instances in lexicographical order.
163 	 *
164 	 * If @bytes1 and @bytes2 have different length but the shorter one is a
165 	 * prefix of the longer one then the shorter one is considered to be less than
166 	 * the longer one. Otherwise the first byte where both differ is used for
167 	 * comparison. If @bytes1 has a smaller value at that position it is
168 	 * considered less, otherwise greater than @bytes2.
169 	 *
170 	 * Params:
171 	 *     bytes2 = a pointer to a #GBytes to compare with @bytes1
172 	 *
173 	 * Returns: a negative value if @bytes1 is less than @bytes2, a positive value
174 	 *     if @bytes1 is greater than @bytes2, and zero if @bytes1 is equal to
175 	 *     @bytes2
176 	 *
177 	 * Since: 2.32
178 	 */
179 	public int compare(Bytes bytes2)
180 	{
181 		return g_bytes_compare(gBytes, (bytes2 is null) ? null : bytes2.getBytesStruct());
182 	}
183 
184 	/**
185 	 * Compares the two #GBytes values being pointed to and returns
186 	 * %TRUE if they are equal.
187 	 *
188 	 * This function can be passed to g_hash_table_new() as the @key_equal_func
189 	 * parameter, when using non-%NULL #GBytes pointers as keys in a #GHashTable.
190 	 *
191 	 * Params:
192 	 *     bytes2 = a pointer to a #GBytes to compare with @bytes1
193 	 *
194 	 * Returns: %TRUE if the two keys match.
195 	 *
196 	 * Since: 2.32
197 	 */
198 	public bool equal(Bytes bytes2)
199 	{
200 		return g_bytes_equal(gBytes, (bytes2 is null) ? null : bytes2.getBytesStruct()) != 0;
201 	}
202 
203 	/**
204 	 * Get the byte data in the #GBytes. This data should not be modified.
205 	 *
206 	 * This function will always return the same pointer for a given #GBytes.
207 	 *
208 	 * %NULL may be returned if @size is 0. This is not guaranteed, as the #GBytes
209 	 * may represent an empty string with @data non-%NULL and @size as 0. %NULL will
210 	 * not be returned if @size is non-zero.
211 	 *
212 	 * Returns: a pointer to the byte data, or %NULL
213 	 *
214 	 * Since: 2.32
215 	 */
216 	public ubyte[] getData()
217 	{
218 		size_t size;
219 
220 		auto p = g_bytes_get_data(gBytes, &size);
221 
222 		return cast(ubyte[])p[0 .. size];
223 	}
224 
225 	/**
226 	 * Get the size of the byte data in the #GBytes.
227 	 *
228 	 * This function will always return the same value for a given #GBytes.
229 	 *
230 	 * Returns: the size
231 	 *
232 	 * Since: 2.32
233 	 */
234 	public size_t getSize()
235 	{
236 		return g_bytes_get_size(gBytes);
237 	}
238 
239 	/**
240 	 * Creates an integer hash code for the byte data in the #GBytes.
241 	 *
242 	 * This function can be passed to g_hash_table_new() as the @key_hash_func
243 	 * parameter, when using non-%NULL #GBytes pointers as keys in a #GHashTable.
244 	 *
245 	 * Returns: a hash value corresponding to the key.
246 	 *
247 	 * Since: 2.32
248 	 */
249 	public uint hash()
250 	{
251 		return g_bytes_hash(gBytes);
252 	}
253 
254 	/**
255 	 * Creates a #GBytes which is a subsection of another #GBytes. The @offset +
256 	 * @length may not be longer than the size of @bytes.
257 	 *
258 	 * A reference to @bytes will be held by the newly created #GBytes until
259 	 * the byte data is no longer needed.
260 	 *
261 	 * Since 2.56, if @offset is 0 and @length matches the size of @bytes, then
262 	 * @bytes will be returned with the reference count incremented by 1. If @bytes
263 	 * is a slice of another #GBytes, then the resulting #GBytes will reference
264 	 * the same #GBytes instead of @bytes. This allows consumers to simplify the
265 	 * usage of #GBytes when asynchronously writing to streams.
266 	 *
267 	 * Params:
268 	 *     offset = offset which subsection starts at
269 	 *     length = length of subsection
270 	 *
271 	 * Returns: a new #GBytes
272 	 *
273 	 * Since: 2.32
274 	 */
275 	public Bytes newFromBytes(size_t offset, size_t length)
276 	{
277 		auto p = g_bytes_new_from_bytes(gBytes, offset, length);
278 
279 		if(p is null)
280 		{
281 			return null;
282 		}
283 
284 		return new Bytes(cast(GBytes*) p, true);
285 	}
286 
287 	alias doref = ref_;
288 	/**
289 	 * Increase the reference count on @bytes.
290 	 *
291 	 * Returns: the #GBytes
292 	 *
293 	 * Since: 2.32
294 	 */
295 	public Bytes ref_()
296 	{
297 		auto p = g_bytes_ref(gBytes);
298 
299 		if(p is null)
300 		{
301 			return null;
302 		}
303 
304 		return new Bytes(cast(GBytes*) p, true);
305 	}
306 
307 	/**
308 	 * Releases a reference on @bytes.  This may result in the bytes being
309 	 * freed. If @bytes is %NULL, it will return immediately.
310 	 *
311 	 * Since: 2.32
312 	 */
313 	public void unref()
314 	{
315 		g_bytes_unref(gBytes);
316 	}
317 
318 	/**
319 	 * Unreferences the bytes, and returns a new mutable #GByteArray containing
320 	 * the same byte data.
321 	 *
322 	 * As an optimization, the byte data is transferred to the array without copying
323 	 * if this was the last reference to bytes and bytes was created with
324 	 * g_bytes_new(), g_bytes_new_take() or g_byte_array_free_to_bytes(). In all
325 	 * other cases the data is copied.
326 	 *
327 	 * Returns: a new mutable #GByteArray containing the same byte data
328 	 *
329 	 * Since: 2.32
330 	 */
331 	public ByteArray unrefToArray()
332 	{
333 		auto p = g_bytes_unref_to_array(gBytes);
334 
335 		if(p is null)
336 		{
337 			return null;
338 		}
339 
340 		return new ByteArray(cast(GByteArray*) p, true);
341 	}
342 
343 	/**
344 	 * Unreferences the bytes, and returns a pointer the same byte data
345 	 * contents.
346 	 *
347 	 * As an optimization, the byte data is returned without copying if this was
348 	 * the last reference to bytes and bytes was created with g_bytes_new(),
349 	 * g_bytes_new_take() or g_byte_array_free_to_bytes(). In all other cases the
350 	 * data is copied.
351 	 *
352 	 * Returns: a pointer to the same byte data, which should be
353 	 *     freed with g_free()
354 	 *
355 	 * Since: 2.32
356 	 */
357 	public ubyte[] unrefToData()
358 	{
359 		size_t size;
360 
361 		auto p = g_bytes_unref_to_data(gBytes, &size);
362 
363 		return cast(ubyte[])p[0 .. size];
364 	}
365 }