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