String

This type holds a null terminated byte array in memory that represents an ASCII encoded text in Gambol. The underlying byte array can actually have any encoding however all functions and methods within this types assume ASCII encoding.

String is an immutable value type that points to a byte array. The memory referred to by this type is not owned by String. The assignment operator only copies the variable not the byte array it points to and therefore passing variables of type String around is efficient.

graph BT
N1["String"] -->|inherits| N2["StringAT"];
N1["String"] -->|inherits| N3["Hashable"];
N1["String"] -->|inherits| N4["Stringable"];
N1["String"] -->|inherits| N5["Length"];
N1["String"] -->|inherits| N6["RandomIterable[Char]"];
N6["RandomIterable[Char]"] -->|inherits| N7["ReverseIterable[Char]"];
N6["RandomIterable[Char]"] -->|inherits| N8["Unpackable[Char]"];
N8["Unpackable[Char]"] -->|inherits| N9["Iterable[Char]"];
N8["Unpackable[Char]"] -->|inherits| N10["UnpackableAT"];
N10["UnpackableAT"] -->|inherits| N5["Length"];
N10["UnpackableAT"] -->|inherits| N11["IterableAT"];
N10["UnpackableAT"] -->|inherits| N12["CollectionAT"];
N12["CollectionAT"] -->|inherits| N13["Any"];
N11["IterableAT"] -->|inherits| N13["Any"];
N5["Length"] -->|inherits| N13["Any"];
N9["Iterable[Char]"] -->|inherits| N11["IterableAT"];
N11["IterableAT"] -->|inherits| N13["Any"];
N7["ReverseIterable[Char]"] -->|inherits| N14["BidirectionalIterable[Char]"];
N14["BidirectionalIterable[Char]"] -->|inherits| N9["Iterable[Char]"];
N9["Iterable[Char]"] -->|inherits| N11["IterableAT"];
N11["IterableAT"] -->|inherits| N13["Any"];
N5["Length"] -->|inherits| N13["Any"];
N4["Stringable"] -->|inherits| N13["Any"];
N3["Hashable"] -->|inherits| N13["Any"];
N2["StringAT"] -->|inherits| N13["Any"];

Characteristics

Quality	Value
Inherits	StringAT, Hashable, Stringable, Length, RandomIterable[Char]
Extends	N/A
Decorators	#Gambol.layout.c;
Is enum	false
Is sealed	false
Is extern	false
Is abstract	false
Is generator	false
Has value semantics	true
Has stored properties	true
Should register destructor	false
Has atomic memory	false
Is copy assignable	true
Is zero initializable	true

Type Aliases

DType

DType = Char

---

Const Expressions

kAsciiLetters

const! kAsciiLetters = `ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz`

String representing all alphabetical ASCII characters.

---

kAsciiLowercase

const! kAsciiLowercase = `abcdefghijklmnopqrstuvwxyz`

String representing all lower-case alphabetical ASCII characters.

---

kAsciiUppercase

const! kAsciiUppercase = `ABCDEFGHIJKLMNOPQRSTUVWXYZ`

String representing all upper-case alphabetical ASCII characters.

---

kDigits

const! kDigits = `0123456789`

String representing all decimal digits in the ASCII character set.

---

kHexDigits

const! kHexDigits = `0123456789abcdefABCDEF`

String representing all hexadecimal digits in the ASCII character set.

---

kOctDigits

const! kOctDigits = `01234567`

String representing all octal digits in the ASCII character set.

---

kPunctuation

const! kPunctuation = `!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~`

String representing all punctuation ASCII characters.

---

kWhitespace

const! kWhitespace = `  

 `

String representing all white space characters in the ASCII character set.

---

kPrintable

const! kPrintable = `   

 !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~`

String representing all printable characters in the ASCII character set.

---

Functions

from_char

from_char (c Char) -> String

creates a String from the given Char

---

from_c_str

from_c_str (cstr Pointer, len Len = -1, make_copy: Bool = true) -> String

creates a String from the given null terminated pointer. if len is < 0 then the length of the String will be computed from cstr first otherwise the correct len must be provided or it will result in undefined behavior. Whether the array pointed to by cstr is copied or not is determined by make_copy.

---

full

full (len Len = 0, with_char Char = 32) -> String

creates a string of length len with all characters set to with_char

---

join

join [T] (container T, delimiter String = ``) -> String

call str on all items in the container and concatenate all the resultant strings into one string delimited by delimiter.

---

translate

translate [T] (s SelfType, table T) -> SelfType

creates a new string that has all characters in this string mapped using the provided table

---

__kmp_compute_lps

__kmp_compute_lps (pattern String) -> List[Len]

---

__kmp_compute_reverse_lps

__kmp_compute_reverse_lps (pattern String) -> List[Len]

---

Methods

construct

#default
#Gambol.function.alwaysinline
construct (s @Self) -> Self

---

allocate

allocate (s @Self, len Len) -> Nil

reset the internal pointer to new memory of size len + 1 and insert the null character at the end.

---

reallocate

reallocate (s @Self, len Len) -> Nil

extend or shrink the internal pointer to len + 1 and insert the null character at the end

---

get_raw_string

get_raw_string (s @Self) -> String

returns a raw string equivalent of this string with backslash and backquotes escaped

---

str

#Gambol.function.alwaysinline
str (s @Self) -> String

---

hash

#Gambol.function.alwaysinline
#strict
hash (s @Self, hasher strictly @ (Pointer, Len) -> Nil) -> Nil

---

len

#strict
#Gambol.function.alwaysinline
len (s @Self) -> Len

---

get_iterator

get_iterator (s @Self) -> StringIterator

---

get_reverse_iterator

get_reverse_iterator (s @Self) -> StringIterator[-1]

---

get_random_iterator

get_random_iterator (s @Self) -> StringRandomIterator

---

c_str

#Gambol.function.alwaysinline
c_str (s @Self) -> PointerToVariable[Char]

---

char_unchecked

#Gambol.function.alwaysinline
char_unchecked (s @Self, index ULen) -> Char

get the char at position index without doing any bounds checking

---

char

char (s @Self, index Len) -> Char

get the char at position index and raise IndexOutOfRangeException if index is out of bounds

---

slice

slice (s @Self, range IndexRange) -> SelfType

create a substring from this string using the given range.

---

find_first

find_first (s @Self, pattern SelfType, range IndexRange?) -> Len

find the first instance of the string pattern in the given range and return the index of the first charater.

range must have a step size of 1 otherwise the function will raise a WrongArgumentException

---

find_last

find_last (s @Self, pattern SelfType, range IndexRange?) -> Len

find the last instance of the string pattern in the given range and return the index of the first charater.

range must have a step size of 1 otherwise the function will raise a WrongArgumentException

---

find

find (s @Self, pattern SelfType, range IndexRange?, overlapping: Bool = true, count: Len = 0) -> List[Len]

finds all instances of the string pattern in the given range up to count items starting from the beginning of the range and returns a list of the first character indices. You can use overlapping to indicate if you want overlapping results or not.

range must have a step size of 1 otherwise the function will raise a WrongArgumentException

---

replace

replace (s @Self, old SelfType, new SelfType, range IndexRange?, count: Len = 0, reverse: Bool = false) -> SelfType

replace all instances of the string old with new in the given range up to count items. You can start either from the beginning of the range or the end using reverse.

range must have a step size of 1 otherwise the function will raise a WrongArgumentException

---

count

count (s @Self, pattern SelfType, range IndexRange?, overlapping: Bool = true) -> Len

count the number of times the string pattern appears in the given range. You can use overlapping to indicate if overlapping instances are acceptable. range must have a step size of 1 otherwise the function will raise a WrongArgumentException

---

rfind

rfind (s @Self, pattern SelfType, range IndexRange?, overlapping: Bool = true, count: Len = 0) -> List[Len]

finds all instances of the string pattern in the given range up to count items starting from the end of the range and returns a list of the first character indices. You can use overlapping to indicate if you want overlapping results or not.

range must have a step size of 1 otherwise the function will raise a WrongArgumentException

---

remove_prefix

remove_prefix (s @Self, prefix SelfType) -> SelfType

return a new string that is equal to this string with the prefix removed

---

remove_suffix

remove_suffix (s @Self, suffix SelfType) -> SelfType

return a new string that is equal to this string with the suffix removed

---

split

split (s @Self, delimiter SelfType, range IndexRange?, count: Len = 0, reverse: Bool = false) -> List[SelfType]

split the string into a list of strings on all instances of delimiter in the given range up to count items starting from the beginning or the end if reverse.

---

capitalize

capitalize (s @Self) -> SelfType

return a new string that's the same as this string but with the first character capitalized

---

center

center (s @Self, width Len, fill_char Char = 32) -> SelfType

adjust the string within the given width to the center using fill_char as filler chraracters.

---

rjust

rjust (s @Self, width Len, fill_char Char = 32) -> SelfType

adjust the string within the given width to the right using fill_char as filler chraracters.

---

ljust

ljust (s @Self, width Len, fill_char Char = 32) -> SelfType

adjust the string within the given width to the left using fill_char as filler chraracters.

---

starts_with

starts_with (s @Self, prefix String, range IndexRange?) -> Bool

returns true of the given range in the string starts with prefix. range must have a step size of 1 or a WrongArgumentException will be raised.

---

ends_with

ends_with (s @Self, suffix String, range IndexRange?) -> Bool

returns true of the given range in the string ends with suffix. range must have a step size of 1 or a WrongArgumentException will be raised.

---

map

map (s @Self, update strictly  (Char) -> Char, range IndexRange?, count: Len = 0, reverse: Bool = false) -> SelfType

returns a new string by applying the update function on each character in the given range up to count characters starting from the beginning of the range or the end if reverse

---

lower

lower (s @Self, range IndexRange?, count: Len = 0, reverse: Bool = false) -> SelfType

returns a new string by turning every character in the given range to lower case up to count characters starting from the beginning of the range or the end if reverse.

---

upper

upper (s @Self, range IndexRange?, count: Len = 0, reverse: Bool = false) -> SelfType

returns a new string by turning every character in the given range to upper case up to count characters starting from the beginning of the range or the end if reverse.

---

swapcase

swapcase (s @Self, range IndexRange?, count: Len = 0, reverse: Bool = false) -> SelfType

returns a new string by turning every character in the given range to the opposite case up to count characters starting from the beginning of the range or the end if reverse.

---

lstrip

lstrip (s @Self, chars SelfType = kWhitespace) -> SelfType

returns a new string that's the same as this one but with any continuous sequence of characters in char removed from the beginning of the string

---

rstrip

rstrip (s @Self, chars SelfType = kWhitespace) -> SelfType

returns a new string that's the same as this one but with any continuous sequence of characters in char removed from the end of the string

---

strip

strip (s @Self, chars SelfType = kWhitespace) -> SelfType

returns a new string that's the same as this one but with any continuous sequence of characters in char removed from the beginning and the end of the string

---

is_lower

is_lower (s @Self, range IndexRange?) -> Bool

true if all characters in range are lower case, false otherwise

---

is_upper

is_upper (s @Self, range IndexRange?) -> Bool

true if all characters in range are upper case, false otherwise

---

is_digit

is_digit (s @Self, range IndexRange?) -> Bool

true if all characters in range are digits, false otherwise

---

is_alpha

is_alpha (s @Self, range IndexRange?) -> Bool

true if all characters in range are alphabetical, false otherwise

---

is_alphanum

is_alphanum (s @Self, range IndexRange?) -> Bool

true if all characters in range are alphanumeric, false otherwise

---

is_punctuation

is_punctuation (s @Self, range IndexRange?) -> Bool

true if all characters in range are punctuations, false otherwise

---

is_space

is_space (s @Self, range IndexRange?) -> Bool

true if all characters in range are space, false otherwise

---

is_null

is_null (s @Self, range IndexRange?) -> Bool

true if all characters in range are null, false otherwise

---

is_printable

is_printable (s @Self, range IndexRange?) -> Bool

true if all characters in range are printable, false otherwise

---

is_extended_ascii

is_extended_ascii (s @Self, range IndexRange?) -> Bool

true if all characters in range are extended ascii characters, false otherwise

---

__set_char_unchecked

#Gambol.function.alwaysinline
__set_char_unchecked (s @Self, val Char, index ULen) -> Char

set the char at position index to val without doing any bounds checking

---

__set_char

__set_char (s @Self, val Char, index Len) -> Char

set the char at position index to val and raise IndexOutOfRangeException if index is out of bounds

---

Binary Operators

=

#default
= (s @Self, o @Self) -> Self

---

==

== (s @Self, o @Self) -> Bool

---

is in

is in (s @Self, pattern String) -> Bool

checks if this string contains the substring pattern

---

>

#Gambol.function.alwaysinline
> (s @Self, o @Self) -> Bool

performs lexicographical comparison between the two strings and returns whether this string is greater than the other

---

>=

#Gambol.function.alwaysinline
>= (s @Self, o @Self) -> Bool

performs lexicographical comparison between the two strings and returns whether this string is greater than or equal to the other

---

<

#Gambol.function.alwaysinline
< (s @Self, o @Self) -> Bool

performs lexicographical comparison between the two strings and returns whether this string is smaller than the other

---

<=

#Gambol.function.alwaysinline
<= (s @Self, o @Self) -> Bool

performs lexicographical comparison between the two strings and returns whether this string is smaller than or equal to the other

---

Properties

__ptr

__ptr PointerToVariable[Char]

---

__len

__len Len

---