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.StringG;
26 
27 private import glib.Bytes;
28 private import glib.Str;
29 private import glib.c.functions;
30 public  import glib.c.types;
31 public  import gtkc.glibtypes;
32 
33 
34 /**
35  * The GString struct contains the public fields of a GString.
36  */
37 public class StringG
38 {
39 	/** the main Gtk struct */
40 	protected GString* gString;
41 	protected bool ownedRef;
42 
43 	/** Get the main Gtk struct */
44 	public GString* getStringGStruct(bool transferOwnership = false)
45 	{
46 		if (transferOwnership)
47 			ownedRef = false;
48 		return gString;
49 	}
50 
51 	/** the main Gtk struct as a void* */
52 	protected void* getStruct()
53 	{
54 		return cast(void*)gString;
55 	}
56 
57 	/**
58 	 * Sets our main struct and passes it to the parent class.
59 	 */
60 	public this (GString* gString, bool ownedRef = false)
61 	{
62 		this.gString = gString;
63 		this.ownedRef = ownedRef;
64 	}
65 
66 
67 	/**
68 	 * Adds a string onto the end of a #GString, expanding
69 	 * it if necessary.
70 	 *
71 	 * Params:
72 	 *     val = the string to append onto the end of @string
73 	 *
74 	 * Returns: @string
75 	 */
76 	public StringG append(string val)
77 	{
78 		auto p = g_string_append(gString, Str.toStringz(val));
79 
80 		if(p is null)
81 		{
82 			return null;
83 		}
84 
85 		return new StringG(cast(GString*) p);
86 	}
87 
88 	/**
89 	 * Adds a byte onto the end of a #GString, expanding
90 	 * it if necessary.
91 	 *
92 	 * Params:
93 	 *     c = the byte to append onto the end of @string
94 	 *
95 	 * Returns: @string
96 	 */
97 	public StringG appendC(char c)
98 	{
99 		auto p = g_string_append_c(gString, c);
100 
101 		if(p is null)
102 		{
103 			return null;
104 		}
105 
106 		return new StringG(cast(GString*) p);
107 	}
108 
109 	/**
110 	 * Appends @len bytes of @val to @string.
111 	 *
112 	 * If @len is positive, @val may contain embedded nuls and need
113 	 * not be nul-terminated. It is the caller's responsibility to
114 	 * ensure that @val has at least @len addressable bytes.
115 	 *
116 	 * If @len is negative, @val must be nul-terminated and @len
117 	 * is considered to request the entire string length. This
118 	 * makes g_string_append_len() equivalent to g_string_append().
119 	 *
120 	 * Params:
121 	 *     val = bytes to append
122 	 *     len = number of bytes of @val to use, or -1 for all of @val
123 	 *
124 	 * Returns: @string
125 	 */
126 	public StringG appendLen(string val, ptrdiff_t len)
127 	{
128 		auto p = g_string_append_len(gString, Str.toStringz(val), len);
129 
130 		if(p is null)
131 		{
132 			return null;
133 		}
134 
135 		return new StringG(cast(GString*) p);
136 	}
137 
138 	/**
139 	 * Converts a Unicode character into UTF-8, and appends it
140 	 * to the string.
141 	 *
142 	 * Params:
143 	 *     wc = a Unicode character
144 	 *
145 	 * Returns: @string
146 	 */
147 	public StringG appendUnichar(dchar wc)
148 	{
149 		auto p = g_string_append_unichar(gString, wc);
150 
151 		if(p is null)
152 		{
153 			return null;
154 		}
155 
156 		return new StringG(cast(GString*) p);
157 	}
158 
159 	/**
160 	 * Appends @unescaped to @string, escaped any characters that
161 	 * are reserved in URIs using URI-style escape sequences.
162 	 *
163 	 * Params:
164 	 *     unescaped = a string
165 	 *     reservedCharsAllowed = a string of reserved characters allowed
166 	 *         to be used, or %NULL
167 	 *     allowUtf8 = set %TRUE if the escaped string may include UTF8 characters
168 	 *
169 	 * Returns: @string
170 	 *
171 	 * Since: 2.16
172 	 */
173 	public StringG appendUriEscaped(string unescaped, string reservedCharsAllowed, bool allowUtf8)
174 	{
175 		auto p = g_string_append_uri_escaped(gString, Str.toStringz(unescaped), Str.toStringz(reservedCharsAllowed), allowUtf8);
176 
177 		if(p is null)
178 		{
179 			return null;
180 		}
181 
182 		return new StringG(cast(GString*) p);
183 	}
184 
185 	/**
186 	 * Appends a formatted string onto the end of a #GString.
187 	 * This function is similar to g_string_append_printf()
188 	 * except that the arguments to the format string are passed
189 	 * as a va_list.
190 	 *
191 	 * Params:
192 	 *     format = the string format. See the printf() documentation
193 	 *     args = the list of arguments to insert in the output
194 	 *
195 	 * Since: 2.14
196 	 */
197 	public void appendVprintf(string format, void* args)
198 	{
199 		g_string_append_vprintf(gString, Str.toStringz(format), args);
200 	}
201 
202 	/**
203 	 * Converts all uppercase ASCII letters to lowercase ASCII letters.
204 	 *
205 	 * Returns: passed-in @string pointer, with all the
206 	 *     uppercase characters converted to lowercase in place,
207 	 *     with semantics that exactly match g_ascii_tolower().
208 	 */
209 	public StringG asciiDown()
210 	{
211 		auto p = g_string_ascii_down(gString);
212 
213 		if(p is null)
214 		{
215 			return null;
216 		}
217 
218 		return new StringG(cast(GString*) p);
219 	}
220 
221 	/**
222 	 * Converts all lowercase ASCII letters to uppercase ASCII letters.
223 	 *
224 	 * Returns: passed-in @string pointer, with all the
225 	 *     lowercase characters converted to uppercase in place,
226 	 *     with semantics that exactly match g_ascii_toupper().
227 	 */
228 	public StringG asciiUp()
229 	{
230 		auto p = g_string_ascii_up(gString);
231 
232 		if(p is null)
233 		{
234 			return null;
235 		}
236 
237 		return new StringG(cast(GString*) p);
238 	}
239 
240 	/**
241 	 * Copies the bytes from a string into a #GString,
242 	 * destroying any previous contents. It is rather like
243 	 * the standard strcpy() function, except that you do not
244 	 * have to worry about having enough space to copy the string.
245 	 *
246 	 * Params:
247 	 *     rval = the string to copy into @string
248 	 *
249 	 * Returns: @string
250 	 */
251 	public StringG assign(string rval)
252 	{
253 		auto p = g_string_assign(gString, Str.toStringz(rval));
254 
255 		if(p is null)
256 		{
257 			return null;
258 		}
259 
260 		return new StringG(cast(GString*) p);
261 	}
262 
263 	/**
264 	 * Converts a #GString to lowercase.
265 	 *
266 	 * Deprecated: This function uses the locale-specific
267 	 * tolower() function, which is almost never the right thing.
268 	 * Use g_string_ascii_down() or g_utf8_strdown() instead.
269 	 *
270 	 * Returns: the #GString
271 	 */
272 	public StringG down()
273 	{
274 		auto p = g_string_down(gString);
275 
276 		if(p is null)
277 		{
278 			return null;
279 		}
280 
281 		return new StringG(cast(GString*) p);
282 	}
283 
284 	/**
285 	 * Compares two strings for equality, returning %TRUE if they are equal.
286 	 * For use with #GHashTable.
287 	 *
288 	 * Params:
289 	 *     v2 = another #GString
290 	 *
291 	 * Returns: %TRUE if the strings are the same length and contain the
292 	 *     same bytes
293 	 */
294 	public bool equal(StringG v2)
295 	{
296 		return g_string_equal(gString, (v2 is null) ? null : v2.getStringGStruct()) != 0;
297 	}
298 
299 	/**
300 	 * Removes @len bytes from a #GString, starting at position @pos.
301 	 * The rest of the #GString is shifted down to fill the gap.
302 	 *
303 	 * Params:
304 	 *     pos = the position of the content to remove
305 	 *     len = the number of bytes to remove, or -1 to remove all
306 	 *         following bytes
307 	 *
308 	 * Returns: @string
309 	 */
310 	public StringG erase(ptrdiff_t pos, ptrdiff_t len)
311 	{
312 		auto p = g_string_erase(gString, pos, len);
313 
314 		if(p is null)
315 		{
316 			return null;
317 		}
318 
319 		return new StringG(cast(GString*) p);
320 	}
321 
322 	/**
323 	 * Frees the memory allocated for the #GString.
324 	 * If @free_segment is %TRUE it also frees the character data.  If
325 	 * it's %FALSE, the caller gains ownership of the buffer and must
326 	 * free it after use with g_free().
327 	 *
328 	 * Params:
329 	 *     freeSegment = if %TRUE, the actual character data is freed as well
330 	 *
331 	 * Returns: the character data of @string
332 	 *     (i.e. %NULL if @free_segment is %TRUE)
333 	 */
334 	public string free(bool freeSegment)
335 	{
336 		auto retStr = g_string_free(gString, freeSegment);
337 
338 		scope(exit) Str.freeString(retStr);
339 		return Str.toString(retStr);
340 	}
341 
342 	/**
343 	 * Transfers ownership of the contents of @string to a newly allocated
344 	 * #GBytes.  The #GString structure itself is deallocated, and it is
345 	 * therefore invalid to use @string after invoking this function.
346 	 *
347 	 * Note that while #GString ensures that its buffer always has a
348 	 * trailing nul character (not reflected in its "len"), the returned
349 	 * #GBytes does not include this extra nul; i.e. it has length exactly
350 	 * equal to the "len" member.
351 	 *
352 	 * Returns: A newly allocated #GBytes containing contents of @string; @string itself is freed
353 	 *
354 	 * Since: 2.34
355 	 */
356 	public Bytes freeToBytes()
357 	{
358 		auto p = g_string_free_to_bytes(gString);
359 
360 		if(p is null)
361 		{
362 			return null;
363 		}
364 
365 		return new Bytes(cast(GBytes*) p, true);
366 	}
367 
368 	/**
369 	 * Creates a hash code for @str; for use with #GHashTable.
370 	 *
371 	 * Returns: hash code for @str
372 	 */
373 	public uint hash()
374 	{
375 		return g_string_hash(gString);
376 	}
377 
378 	/**
379 	 * Inserts a copy of a string into a #GString,
380 	 * expanding it if necessary.
381 	 *
382 	 * Params:
383 	 *     pos = the position to insert the copy of the string
384 	 *     val = the string to insert
385 	 *
386 	 * Returns: @string
387 	 */
388 	public StringG insert(ptrdiff_t pos, string val)
389 	{
390 		auto p = g_string_insert(gString, pos, Str.toStringz(val));
391 
392 		if(p is null)
393 		{
394 			return null;
395 		}
396 
397 		return new StringG(cast(GString*) p);
398 	}
399 
400 	/**
401 	 * Inserts a byte into a #GString, expanding it if necessary.
402 	 *
403 	 * Params:
404 	 *     pos = the position to insert the byte
405 	 *     c = the byte to insert
406 	 *
407 	 * Returns: @string
408 	 */
409 	public StringG insertC(ptrdiff_t pos, char c)
410 	{
411 		auto p = g_string_insert_c(gString, pos, c);
412 
413 		if(p is null)
414 		{
415 			return null;
416 		}
417 
418 		return new StringG(cast(GString*) p);
419 	}
420 
421 	/**
422 	 * Inserts @len bytes of @val into @string at @pos.
423 	 *
424 	 * If @len is positive, @val may contain embedded nuls and need
425 	 * not be nul-terminated. It is the caller's responsibility to
426 	 * ensure that @val has at least @len addressable bytes.
427 	 *
428 	 * If @len is negative, @val must be nul-terminated and @len
429 	 * is considered to request the entire string length.
430 	 *
431 	 * If @pos is -1, bytes are inserted at the end of the string.
432 	 *
433 	 * Params:
434 	 *     pos = position in @string where insertion should
435 	 *         happen, or -1 for at the end
436 	 *     val = bytes to insert
437 	 *     len = number of bytes of @val to insert, or -1 for all of @val
438 	 *
439 	 * Returns: @string
440 	 */
441 	public StringG insertLen(ptrdiff_t pos, string val, ptrdiff_t len)
442 	{
443 		auto p = g_string_insert_len(gString, pos, Str.toStringz(val), len);
444 
445 		if(p is null)
446 		{
447 			return null;
448 		}
449 
450 		return new StringG(cast(GString*) p);
451 	}
452 
453 	/**
454 	 * Converts a Unicode character into UTF-8, and insert it
455 	 * into the string at the given position.
456 	 *
457 	 * Params:
458 	 *     pos = the position at which to insert character, or -1
459 	 *         to append at the end of the string
460 	 *     wc = a Unicode character
461 	 *
462 	 * Returns: @string
463 	 */
464 	public StringG insertUnichar(ptrdiff_t pos, dchar wc)
465 	{
466 		auto p = g_string_insert_unichar(gString, pos, wc);
467 
468 		if(p is null)
469 		{
470 			return null;
471 		}
472 
473 		return new StringG(cast(GString*) p);
474 	}
475 
476 	/**
477 	 * Overwrites part of a string, lengthening it if necessary.
478 	 *
479 	 * Params:
480 	 *     pos = the position at which to start overwriting
481 	 *     val = the string that will overwrite the @string starting at @pos
482 	 *
483 	 * Returns: @string
484 	 *
485 	 * Since: 2.14
486 	 */
487 	public StringG overwrite(size_t pos, string val)
488 	{
489 		auto p = g_string_overwrite(gString, pos, Str.toStringz(val));
490 
491 		if(p is null)
492 		{
493 			return null;
494 		}
495 
496 		return new StringG(cast(GString*) p);
497 	}
498 
499 	/**
500 	 * Overwrites part of a string, lengthening it if necessary.
501 	 * This function will work with embedded nuls.
502 	 *
503 	 * Params:
504 	 *     pos = the position at which to start overwriting
505 	 *     val = the string that will overwrite the @string starting at @pos
506 	 *     len = the number of bytes to write from @val
507 	 *
508 	 * Returns: @string
509 	 *
510 	 * Since: 2.14
511 	 */
512 	public StringG overwriteLen(size_t pos, string val, ptrdiff_t len)
513 	{
514 		auto p = g_string_overwrite_len(gString, pos, Str.toStringz(val), len);
515 
516 		if(p is null)
517 		{
518 			return null;
519 		}
520 
521 		return new StringG(cast(GString*) p);
522 	}
523 
524 	/**
525 	 * Adds a string on to the start of a #GString,
526 	 * expanding it if necessary.
527 	 *
528 	 * Params:
529 	 *     val = the string to prepend on the start of @string
530 	 *
531 	 * Returns: @string
532 	 */
533 	public StringG prepend(string val)
534 	{
535 		auto p = g_string_prepend(gString, Str.toStringz(val));
536 
537 		if(p is null)
538 		{
539 			return null;
540 		}
541 
542 		return new StringG(cast(GString*) p);
543 	}
544 
545 	/**
546 	 * Adds a byte onto the start of a #GString,
547 	 * expanding it if necessary.
548 	 *
549 	 * Params:
550 	 *     c = the byte to prepend on the start of the #GString
551 	 *
552 	 * Returns: @string
553 	 */
554 	public StringG prependC(char c)
555 	{
556 		auto p = g_string_prepend_c(gString, c);
557 
558 		if(p is null)
559 		{
560 			return null;
561 		}
562 
563 		return new StringG(cast(GString*) p);
564 	}
565 
566 	/**
567 	 * Prepends @len bytes of @val to @string.
568 	 *
569 	 * If @len is positive, @val may contain embedded nuls and need
570 	 * not be nul-terminated. It is the caller's responsibility to
571 	 * ensure that @val has at least @len addressable bytes.
572 	 *
573 	 * If @len is negative, @val must be nul-terminated and @len
574 	 * is considered to request the entire string length. This
575 	 * makes g_string_prepend_len() equivalent to g_string_prepend().
576 	 *
577 	 * Params:
578 	 *     val = bytes to prepend
579 	 *     len = number of bytes in @val to prepend, or -1 for all of @val
580 	 *
581 	 * Returns: @string
582 	 */
583 	public StringG prependLen(string val, ptrdiff_t len)
584 	{
585 		auto p = g_string_prepend_len(gString, Str.toStringz(val), len);
586 
587 		if(p is null)
588 		{
589 			return null;
590 		}
591 
592 		return new StringG(cast(GString*) p);
593 	}
594 
595 	/**
596 	 * Converts a Unicode character into UTF-8, and prepends it
597 	 * to the string.
598 	 *
599 	 * Params:
600 	 *     wc = a Unicode character
601 	 *
602 	 * Returns: @string
603 	 */
604 	public StringG prependUnichar(dchar wc)
605 	{
606 		auto p = g_string_prepend_unichar(gString, wc);
607 
608 		if(p is null)
609 		{
610 			return null;
611 		}
612 
613 		return new StringG(cast(GString*) p);
614 	}
615 
616 	/**
617 	 * Sets the length of a #GString. If the length is less than
618 	 * the current length, the string will be truncated. If the
619 	 * length is greater than the current length, the contents
620 	 * of the newly added area are undefined. (However, as
621 	 * always, string->str[string->len] will be a nul byte.)
622 	 *
623 	 * Params:
624 	 *     len = the new length
625 	 *
626 	 * Returns: @string
627 	 */
628 	public StringG setSize(size_t len)
629 	{
630 		auto p = g_string_set_size(gString, len);
631 
632 		if(p is null)
633 		{
634 			return null;
635 		}
636 
637 		return new StringG(cast(GString*) p);
638 	}
639 
640 	/**
641 	 * Cuts off the end of the GString, leaving the first @len bytes.
642 	 *
643 	 * Params:
644 	 *     len = the new size of @string
645 	 *
646 	 * Returns: @string
647 	 */
648 	public StringG truncate(size_t len)
649 	{
650 		auto p = g_string_truncate(gString, len);
651 
652 		if(p is null)
653 		{
654 			return null;
655 		}
656 
657 		return new StringG(cast(GString*) p);
658 	}
659 
660 	/**
661 	 * Converts a #GString to uppercase.
662 	 *
663 	 * Deprecated: This function uses the locale-specific
664 	 * toupper() function, which is almost never the right thing.
665 	 * Use g_string_ascii_up() or g_utf8_strup() instead.
666 	 *
667 	 * Returns: @string
668 	 */
669 	public StringG up()
670 	{
671 		auto p = g_string_up(gString);
672 
673 		if(p is null)
674 		{
675 			return null;
676 		}
677 
678 		return new StringG(cast(GString*) p);
679 	}
680 
681 	/**
682 	 * Writes a formatted string into a #GString.
683 	 * This function is similar to g_string_printf() except that
684 	 * the arguments to the format string are passed as a va_list.
685 	 *
686 	 * Params:
687 	 *     format = the string format. See the printf() documentation
688 	 *     args = the parameters to insert into the format string
689 	 *
690 	 * Since: 2.14
691 	 */
692 	public void vprintf(string format, void* args)
693 	{
694 		g_string_vprintf(gString, Str.toStringz(format), args);
695 	}
696 
697 	/**
698 	 * Creates a new #GString, initialized with the given string.
699 	 *
700 	 * Params:
701 	 *     init = the initial text to copy into the string, or %NULL to
702 	 *         start with an empty string
703 	 *
704 	 * Returns: the new #GString
705 	 */
706 	public static StringG stringNew(string init)
707 	{
708 		auto p = g_string_new(Str.toStringz(init));
709 
710 		if(p is null)
711 		{
712 			return null;
713 		}
714 
715 		return new StringG(cast(GString*) p, true);
716 	}
717 
718 	/**
719 	 * Creates a new #GString with @len bytes of the @init buffer.
720 	 * Because a length is provided, @init need not be nul-terminated,
721 	 * and can contain embedded nul bytes.
722 	 *
723 	 * Since this function does not stop at nul bytes, it is the caller's
724 	 * responsibility to ensure that @init has at least @len addressable
725 	 * bytes.
726 	 *
727 	 * Params:
728 	 *     init = initial contents of the string
729 	 *     len = length of @init to use
730 	 *
731 	 * Returns: a new #GString
732 	 */
733 	public static StringG stringNewLen(string init, ptrdiff_t len)
734 	{
735 		auto p = g_string_new_len(Str.toStringz(init), len);
736 
737 		if(p is null)
738 		{
739 			return null;
740 		}
741 
742 		return new StringG(cast(GString*) p, true);
743 	}
744 
745 	/**
746 	 * Creates a new #GString, with enough space for @dfl_size
747 	 * bytes. This is useful if you are going to add a lot of
748 	 * text to the string and don't want it to be reallocated
749 	 * too often.
750 	 *
751 	 * Params:
752 	 *     dflSize = the default size of the space allocated to
753 	 *         hold the string
754 	 *
755 	 * Returns: the new #GString
756 	 */
757 	public static StringG stringSizedNew(size_t dflSize)
758 	{
759 		auto p = g_string_sized_new(dflSize);
760 
761 		if(p is null)
762 		{
763 			return null;
764 		}
765 
766 		return new StringG(cast(GString*) p, true);
767 	}
768 }