source: appstream-generator/build/girepo/glib/Bytes.d @ 4841

Last change on this file since 4841 was 4841, checked in by Juanma, 2 years ago

Initial release

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