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 * Creates a new #GBytes from @data. 89 * 90 * @data is copied. If @size is 0, @data may be %NULL. 91 * 92 * Params: 93 * data = the data to be used for the bytes 94 * size = the size of @data 95 * 96 * Return: a new #GBytes 97 * 98 * Since: 2.32 99 * 100 * Throws: ConstructionException GTK+ fails to create the object. 101 */ 102 public this(ubyte[] data) 103 { 104 auto p = g_bytes_new(data.ptr, cast(size_t)data.length); 105 106 if(p is null) 107 { 108 throw new ConstructionException("null returned by new"); 109 } 110 111 this(cast(GBytes*) p); 112 } 113 114 /** 115 * Creates a #GBytes from @data. 116 * 117 * When the last reference is dropped, @free_func will be called with the 118 * @user_data argument. 119 * 120 * @data must not be modified after this call is made until @free_func has 121 * been called to indicate that the bytes is no longer in use. 122 * 123 * @data may be %NULL if @size is 0. 124 * 125 * Params: 126 * data = the data to be used for the bytes 127 * size = the size of @data 128 * freeFunc = the function to call to release the data 129 * userData = data to pass to @free_func 130 * 131 * Return: a new #GBytes 132 * 133 * Since: 2.32 134 * 135 * Throws: ConstructionException GTK+ fails to create the object. 136 */ 137 public this(void[] data, GDestroyNotify freeFunc, void* userData) 138 { 139 auto p = g_bytes_new_with_free_func(data.ptr, cast(size_t)data.length, freeFunc, userData); 140 141 if(p is null) 142 { 143 throw new ConstructionException("null returned by new_with_free_func"); 144 } 145 146 this(cast(GBytes*) p); 147 } 148 149 /** 150 * Compares the two #GBytes values. 151 * 152 * This function can be used to sort GBytes instances in lexographical order. 153 * 154 * Params: 155 * bytes2 = a pointer to a #GBytes to compare with @bytes1 156 * 157 * Return: a negative value if bytes2 is lesser, a positive value if bytes2 is 158 * greater, and zero if bytes2 is equal to bytes1 159 * 160 * Since: 2.32 161 */ 162 public int compare(Bytes bytes2) 163 { 164 return g_bytes_compare(gBytes, (bytes2 is null) ? null : bytes2.getBytesStruct()); 165 } 166 167 /** 168 * Compares the two #GBytes values being pointed to and returns 169 * %TRUE if they are equal. 170 * 171 * This function can be passed to g_hash_table_new() as the @key_equal_func 172 * parameter, when using non-%NULL #GBytes pointers as keys in a #GHashTable. 173 * 174 * Params: 175 * bytes2 = a pointer to a #GBytes to compare with @bytes1 176 * 177 * Return: %TRUE if the two keys match. 178 * 179 * Since: 2.32 180 */ 181 public bool equal(Bytes bytes2) 182 { 183 return g_bytes_equal(gBytes, (bytes2 is null) ? null : bytes2.getBytesStruct()) != 0; 184 } 185 186 /** 187 * Get the byte data in the #GBytes. This data should not be modified. 188 * 189 * This function will always return the same pointer for a given #GBytes. 190 * 191 * %NULL may be returned if @size is 0. This is not guaranteed, as the #GBytes 192 * may represent an empty string with @data non-%NULL and @size as 0. %NULL will 193 * not be returned if @size is non-zero. 194 * 195 * Return: a pointer to the 196 * byte data, or %NULL 197 * 198 * Since: 2.32 199 */ 200 public void[] getData() 201 { 202 size_t size; 203 204 auto p = g_bytes_get_data(gBytes, &size); 205 206 return p[0 .. size]; 207 } 208 209 /** 210 * Get the size of the byte data in the #GBytes. 211 * 212 * This function will always return the same value for a given #GBytes. 213 * 214 * Return: the size 215 * 216 * Since: 2.32 217 */ 218 public size_t getSize() 219 { 220 return g_bytes_get_size(gBytes); 221 } 222 223 /** 224 * Creates an integer hash code for the byte data in the #GBytes. 225 * 226 * This function can be passed to g_hash_table_new() as the @key_hash_func 227 * parameter, when using non-%NULL #GBytes pointers as keys in a #GHashTable. 228 * 229 * Return: a hash value corresponding to the key. 230 * 231 * Since: 2.32 232 */ 233 public uint hash() 234 { 235 return g_bytes_hash(gBytes); 236 } 237 238 /** 239 * Creates a #GBytes which is a subsection of another #GBytes. The @offset + 240 * @length may not be longer than the size of @bytes. 241 * 242 * A reference to @bytes will be held by the newly created #GBytes until 243 * the byte data is no longer needed. 244 * 245 * Params: 246 * offset = offset which subsection starts at 247 * length = length of subsection 248 * 249 * Return: a new #GBytes 250 * 251 * Since: 2.32 252 */ 253 public Bytes newFromBytes(size_t offset, size_t length) 254 { 255 auto p = g_bytes_new_from_bytes(gBytes, offset, length); 256 257 if(p is null) 258 { 259 return null; 260 } 261 262 return new Bytes(cast(GBytes*) p); 263 } 264 265 /** 266 * Increase the reference count on @bytes. 267 * 268 * Return: the #GBytes 269 * 270 * Since: 2.32 271 */ 272 public Bytes doref() 273 { 274 auto p = g_bytes_ref(gBytes); 275 276 if(p is null) 277 { 278 return null; 279 } 280 281 return new Bytes(cast(GBytes*) p); 282 } 283 284 /** 285 * Releases a reference on @bytes. This may result in the bytes being 286 * freed. 287 * 288 * Since: 2.32 289 */ 290 public void unref() 291 { 292 g_bytes_unref(gBytes); 293 } 294 295 /** 296 * Unreferences the bytes, and returns a new mutable #GByteArray containing 297 * the same byte data. 298 * 299 * As an optimization, the byte data is transferred to the array without copying 300 * if this was the last reference to bytes and bytes was created with 301 * g_bytes_new(), g_bytes_new_take() or g_byte_array_free_to_bytes(). In all 302 * other cases the data is copied. 303 * 304 * Return: a new mutable #GByteArray containing the same byte data 305 * 306 * Since: 2.32 307 */ 308 public ByteArray unrefToArray() 309 { 310 auto p = g_bytes_unref_to_array(gBytes); 311 312 if(p is null) 313 { 314 return null; 315 } 316 317 return new ByteArray(cast(GByteArray*) p); 318 } 319 320 /** 321 * Unreferences the bytes, and returns a pointer the same byte data 322 * contents. 323 * 324 * As an optimization, the byte data is returned without copying if this was 325 * the last reference to bytes and bytes was created with g_bytes_new(), 326 * g_bytes_new_take() or g_byte_array_free_to_bytes(). In all other cases the 327 * data is copied. 328 * 329 * Params: 330 * size = location to place the length of the returned data 331 * 332 * Return: a pointer to the same byte data, which should 333 * be freed with g_free() 334 * 335 * Since: 2.32 336 */ 337 public void* unrefToData(size_t* size) 338 { 339 return g_bytes_unref_to_data(gBytes, size); 340 } 341 }