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 lexographical order. 163 * 164 * Params: 165 * bytes2 = a pointer to a #GBytes to compare with @bytes1 166 * 167 * Returns: a negative value if bytes2 is lesser, a positive value if bytes2 is 168 * greater, and zero if bytes2 is equal to bytes1 169 * 170 * Since: 2.32 171 */ 172 public int compare(Bytes bytes2) 173 { 174 return g_bytes_compare(gBytes, (bytes2 is null) ? null : bytes2.getBytesStruct()); 175 } 176 177 /** 178 * Compares the two #GBytes values being pointed to and returns 179 * %TRUE if they are equal. 180 * 181 * This function can be passed to g_hash_table_new() as the @key_equal_func 182 * parameter, when using non-%NULL #GBytes pointers as keys in a #GHashTable. 183 * 184 * Params: 185 * bytes2 = a pointer to a #GBytes to compare with @bytes1 186 * 187 * Returns: %TRUE if the two keys match. 188 * 189 * Since: 2.32 190 */ 191 public bool equal(Bytes bytes2) 192 { 193 return g_bytes_equal(gBytes, (bytes2 is null) ? null : bytes2.getBytesStruct()) != 0; 194 } 195 196 /** 197 * Get the byte data in the #GBytes. This data should not be modified. 198 * 199 * This function will always return the same pointer for a given #GBytes. 200 * 201 * %NULL may be returned if @size is 0. This is not guaranteed, as the #GBytes 202 * may represent an empty string with @data non-%NULL and @size as 0. %NULL will 203 * not be returned if @size is non-zero. 204 * 205 * Returns: a pointer to the byte data, or %NULL 206 * 207 * Since: 2.32 208 */ 209 public ubyte[] getData() 210 { 211 size_t size; 212 213 auto p = g_bytes_get_data(gBytes, &size); 214 215 return cast(ubyte[])p[0 .. size]; 216 } 217 218 /** 219 * Get the size of the byte data in the #GBytes. 220 * 221 * This function will always return the same value for a given #GBytes. 222 * 223 * Returns: the size 224 * 225 * Since: 2.32 226 */ 227 public size_t getSize() 228 { 229 return g_bytes_get_size(gBytes); 230 } 231 232 /** 233 * Creates an integer hash code for the byte data in the #GBytes. 234 * 235 * This function can be passed to g_hash_table_new() as the @key_hash_func 236 * parameter, when using non-%NULL #GBytes pointers as keys in a #GHashTable. 237 * 238 * Returns: a hash value corresponding to the key. 239 * 240 * Since: 2.32 241 */ 242 public uint hash() 243 { 244 return g_bytes_hash(gBytes); 245 } 246 247 /** 248 * Creates a #GBytes which is a subsection of another #GBytes. The @offset + 249 * @length may not be longer than the size of @bytes. 250 * 251 * A reference to @bytes will be held by the newly created #GBytes until 252 * the byte data is no longer needed. 253 * 254 * Params: 255 * offset = offset which subsection starts at 256 * length = length of subsection 257 * 258 * Returns: a new #GBytes 259 * 260 * Since: 2.32 261 */ 262 public Bytes newFromBytes(size_t offset, size_t length) 263 { 264 auto p = g_bytes_new_from_bytes(gBytes, offset, length); 265 266 if(p is null) 267 { 268 return null; 269 } 270 271 return new Bytes(cast(GBytes*) p, true); 272 } 273 274 /** 275 * Increase the reference count on @bytes. 276 * 277 * Returns: the #GBytes 278 * 279 * Since: 2.32 280 */ 281 public Bytes doref() 282 { 283 auto p = g_bytes_ref(gBytes); 284 285 if(p is null) 286 { 287 return null; 288 } 289 290 return new Bytes(cast(GBytes*) p, true); 291 } 292 293 /** 294 * Releases a reference on @bytes. This may result in the bytes being 295 * freed. 296 * 297 * Since: 2.32 298 */ 299 public void unref() 300 { 301 g_bytes_unref(gBytes); 302 } 303 304 /** 305 * Unreferences the bytes, and returns a new mutable #GByteArray containing 306 * the same byte data. 307 * 308 * As an optimization, the byte data is transferred to the array without copying 309 * if this was the last reference to bytes and bytes was created with 310 * g_bytes_new(), g_bytes_new_take() or g_byte_array_free_to_bytes(). In all 311 * other cases the data is copied. 312 * 313 * Returns: a new mutable #GByteArray containing the same byte data 314 * 315 * Since: 2.32 316 */ 317 public ByteArray unrefToArray() 318 { 319 auto p = g_bytes_unref_to_array(gBytes); 320 321 if(p is null) 322 { 323 return null; 324 } 325 326 return new ByteArray(cast(GByteArray*) p, true); 327 } 328 329 /** 330 * Unreferences the bytes, and returns a pointer the same byte data 331 * contents. 332 * 333 * As an optimization, the byte data is returned without copying if this was 334 * the last reference to bytes and bytes was created with g_bytes_new(), 335 * g_bytes_new_take() or g_byte_array_free_to_bytes(). In all other cases the 336 * data is copied. 337 * 338 * Returns: a pointer to the same byte data, which should be 339 * freed with g_free() 340 * 341 * Since: 2.32 342 */ 343 public ubyte[] unrefToData() 344 { 345 size_t size; 346 347 auto p = g_bytes_unref_to_data(gBytes, &size); 348 349 return cast(ubyte[])p[0 .. size]; 350 } 351 }