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