std.string.String
Atomicclass pub builtin String
An UTF-8 encoded and immutable string type.
Static methods
from_pointer
Show source codeHide source code
fn pub static from_pointer(pointer: Pointer[UInt8]) -> String {
inko_string_from_pointer(_INKO.state, pointer)
}
fn pub static from_pointer(pointer: Pointer[UInt8]) -> String
Returns a String
created from the given NULL terminated pointer.
The purpose of this method is to allow creating a String
from a pointer
returned by C code. While this method ensures the input is valid UTF-8, it
may crash your program if given an invalid pointer (e.g. a NULL pointer).
Do not use this method unless you have somehow verified that the pointer is a valid NULL terminated C string.
Examples
String.from_pointer("hello".to_pointer) == "hello" # => true
join
Show source codeHide source code
fn pub static join[T: ToString, I: Iter[T]](
iter: move I,
with: String,
) -> String {
let result = iter.reduce(StringBuffer.new, fn (buff, val) {
if buff.size > 0 { buff.push(with) }
buff.push(val.to_string)
buff
})
result.to_string
}
fn pub static join[T: ToString, I: Iter[T]](iter: move I, with: String) -> String
Return a String
that contains the values of the iterator, separated by the
value of the with
argument.
Examples
let vals = [10, 20, 30].into_iter
String.join(vals, with: ',') => '10,20,30'
Instance methods
!=
Show source codeHide source code
fn pub !=(other: T) -> Bool {
(self == other).false?
}
fn pub !=(other: T) -> Bool
Returns true
if self
and the given object are not equal to each other.
+
Show source codeHide source code
fn pub +(other: ref String) -> String {
_INKO.string_concat(self, other)
}
fn pub +(other: ref String) -> String
Concatenates self
and the given String
, returning a new String
.
Examples
'hello ' + 'world' # => 'hello world'
<
Show source codeHide source code
fn pub <(other: ref T) -> Bool {
match cmp(other) {
case Less -> true
case _ -> false
}
}
fn pub <(other: ref T) -> Bool
Returns true
if self
is lower than the given argument.
<=
Show source codeHide source code
fn pub <=(other: ref T) -> Bool {
match cmp(other) {
case Less or Equal -> true
case _ -> false
}
}
fn pub <=(other: ref T) -> Bool
Returns true
if self
is lower than or equal to the given argument.
==
Show source codeHide source code
fn pub ==(other: ref String) -> Bool {
let size = self.size
if size != other.size { return false }
let mut idx = 0
while idx < size {
if byte_unchecked(idx) != other.byte_unchecked(idx) { return false }
idx += 1
}
true
}
fn pub ==(other: ref String) -> Bool
Returns true
if the current String
and other
are equal to each other.
Examples
Returns true
if two Strings are equal:
'foo' == 'foo' # => true
Returns false
if two Strings are not equal:
'foo' == 'bar' # => false
>
Show source codeHide source code
fn pub >(other: ref T) -> Bool {
match cmp(other) {
case Greater -> true
case _ -> false
}
}
fn pub >(other: ref T) -> Bool
Returns true
if self
is greater than the given argument.
>=
Show source codeHide source code
fn pub >=(other: ref T) -> Bool {
match cmp(other) {
case Greater or Equal -> true
case _ -> false
}
}
fn pub >=(other: ref T) -> Bool
Returns true
if self
is equal to or greater than the given argument.
byte
Show source codeHide source code
fn pub byte(index: Int) -> Int {
bounds_check(index, size)
byte_unchecked(index)
}
fn pub byte(index: Int) -> Int
Returns the byte at the given byte index.
Examples
Obtaining a single byte from a String
:
'inko'.byte(0) # => 105
Panics
If the index is out of bounds, this method panics.
byte_index
Show source codeHide source code
fn pub byte_index(of: String, starting_at: Int) -> Option[Int] {
# This is a naive string searching algorithm (see
# https://en.wikipedia.org/wiki/String-searching_algorithm) for more details
# on the various algorithms.
#
# We're using the naive algorithm because:
#
# 1. It's easy to implement
# 2. It doesn't require any pre-processing
# 3. At the time of writing there was no need for something more performant
let find_size = of.size
if find_size == 0 or size == 0 or find_size > size { return Option.None }
let mut a = starting_at
let max = size - find_size
while a <= max {
let mut b = 0
while b < find_size and byte(a + b) == of.byte(b) { b += 1 }
if b == find_size { return Option.Some(a) }
a += 1
}
Option.None
}
fn pub byte_index(of: String, starting_at: Int) -> Option[Int]
Returns the byte index of the first occurrence of the given String
,
starting at the given byte index.
Examples
'hello'.byte_index(of: 'h', starting_at: 0) # => Option.Some(0)
'hello'.byte_index(of: 'l', starting_at: 0) # => Option.Some(2)
'hello'.byte_index(of: 'l', starting_at: 3) # => Option.Some(3)
'hello'.byte_index(of: 'x', starting_at: 0) # => Option.None
bytes
Show source codeHide source code
fn pub bytes -> Stream[Int] {
let mut idx = 0
let max = size
Stream.new(fn move {
if idx < max { Option.Some(byte(idx := idx + 1)) } else { Option.None }
})
}
fn pub bytes -> Stream[Int]
Returns an iterator over the bytes in self
.
chars
Show source codeHide source code
fn pub chars -> Chars {
Chars(string: self, iter: inko_string_chars(self))
}
fn pub chars -> Chars
Returns an iterator over the characters (= extended grapheme clusters) in
self
.
Examples
'๐๐'.chars.next # => Option.Some('๐')
clone
Show source codeHide source code
fn pub clone -> String {
self
}
fn pub clone -> String
Creates a clone of self
.
cmp
Show source codeHide source code
fn pub cmp(other: String) -> Ordering {
let mut max = min(size, other.size)
let mut idx = 0
while idx < max {
match byte_unchecked(idx).cmp(other.byte_unchecked(idx)) {
case Equal -> idx += 1
case ord -> return ord
}
}
size.cmp(other.size)
}
fn pub cmp(other: String) -> Ordering
Performs a byte-wise comparison of self
with other
.
This method does not perform lexicographic sorting, and thus produces unreliable results for multi-byte strings.
Examples
'aaa'.cmp('bbb') # => Ordering.Less 'aab'.cmp('aaa') # => Ordering.Greater
contains?
Show source codeHide source code
fn pub contains?(value: ref String) -> Bool {
byte_index(of: value, starting_at: 0).some?
}
fn pub contains?(value: ref String) -> Bool
Returns true
if the given value is contained in self
.
empty?
Show source codeHide source code
fn pub empty? -> Bool {
size == 0
}
fn pub empty? -> Bool
Returns true
if self
is an empty String
.
Examples
''.empty? # => true
'foo'.empty? # => false
ends_with?
Show source codeHide source code
fn pub ends_with?(suffix: String) -> Bool {
byte_index(of: suffix, starting_at: size - suffix.size).some?
}
fn pub ends_with?(suffix: String) -> Bool
Returns true
if self
ends with the given String
.
Examples
Checking if a String
ends with another String
:
'hello_world'.ends_with?('world') # => true
'hello'.ends_with?('world') # => false
escaped
Show source codeHide source code
fn pub escaped -> String {
let buff = ByteArray.new
let max = ESCAPE_TABLE.size
bytes.each(fn (byte) {
if byte >= max {
buff.push(byte)
return
}
match ESCAPE_TABLE.get(byte) {
case -1 -> buff.push(byte)
case byte -> {
buff.push(BSLASH)
buff.push(byte)
}
}
})
buff.into_string
}
fn pub escaped -> String
Returns a copy of self
with all special characters escaped.
The following characters are escaped:
- Double quotes
- Tabs
- Newlines
- Carriage returns
- Backspace
- Form feed
- Backslash
Examples
"hello\nworld" # => 'hello\nworld'
"hello\\world" # => 'hello\\world'
fmt
Show source codeHide source code
fn pub fmt(formatter: mut Formatter) {
formatter.write('"')
formatter.write(escaped)
formatter.write('"')
}
fn pub fmt(formatter: mut Formatter)
Formats self
in a human-readable format for debugging purposes.
hash
Show source codeHide source code
fn pub hash[H: mut + Hasher](hasher: mut H) {
let mut index = 0
while index < size {
hasher.write(byte_unchecked(index))
index += 1
}
}
fn pub hash[H: mut + Hasher](hasher: mut H: mut)
Writes the hash for self
into the given Hasher
.
into_byte_array
Show source codeHide source code
fn pub move into_byte_array -> ByteArray {
to_byte_array
}
fn pub move into_byte_array -> ByteArray
into_string
Show source codeHide source code
fn pub move into_string -> String {
self
}
fn pub move into_string -> String
Moves self
into a String
.
pad_end
Show source codeHide source code
fn pub pad_end(with: String, chars: Int) -> String {
self + padding(with, chars: self.chars.count, pad_to: chars)
}
fn pub pad_end(with: String, chars: Int) -> String
Returns a new String
that is padded with another String
until the given
number of characters is reached.
The padding is applied at the end of the new String
.
Examples
'hello'.pad_end(with: ' ', chars: 7) # => 'hello '
'hello'.pad_end(with: ' ', chars: 5) # => 'hello'
pad_start
Show source codeHide source code
fn pub pad_start(with: String, chars: Int) -> String {
padding(with, chars: self.chars.count, pad_to: chars) + self
}
fn pub pad_start(with: String, chars: Int) -> String
Returns a new String
that is padded with another String
until the given
number of characters is reached.
The padding is applied at the start of the new String
.
Examples
'hello'.pad_start(with: ' ', chars: 7) # => ' hello'
'hello'.pad_start(with: ' ', chars: 5) # => 'hello'
repeat
Show source codeHide source code
fn pub repeat(times: Int) -> String {
match times {
case 0 -> ''
case 1 -> self
case _ -> {
let buf = StringBuffer.new
times.times(fn (_) { buf.push(clone) })
buf.into_string
}
}
}
fn pub repeat(times: Int) -> String
Returns a new String
that contains self
multiple times.
Examples
'a'.repeat(4) # => 'aaaa'
replace
Show source codeHide source code
fn pub replace(string: String, with: String) -> String {
# Different languages handle the pattern being empty differently. For
# example, Javascript and Node only match the start of the string if the
# pattern is empty. Other languages such as Ruby and Python appear to inject
# the replacement in between every character, such that
# `'AB'.replace('', ',')` results in `,A,B,`.
#
# We make the decision to just _not_ do any replacements in this case, as
# replacing an empty string is nonsensical to begin with.
if string.size == 0 { return self }
let buf = ByteArray.new
let mut start = 0
let mut last = 0
loop {
match byte_index(string, start) {
case Some(i) -> {
if i > last { slice_into(buf, start: last, size: i - last) }
with.slice_into(buf, start: 0, size: with.size)
start = i + string.size
last = start
}
case _ -> {
if start < size { slice_into(buf, start, size) }
break
}
}
}
buf.into_string
}
fn pub replace(string: String, with: String) -> String
Replaces all occurrences of string
with the value in with
, returning the
result as a new String
.
If the string
argument is an empty String
, this method doesn't perform
any replacements and instead returns a copy of self
.
Examples
'foo foo'.replace('foo', with: 'bar') # => 'bar bar'
size
Show source codeHide source code
fn pub size -> Int {
@size as Int
}
fn pub size -> Int
Returns the size of the String
in bytes.
Examples
Getting the byte size of a String
:
'foo'.size # => 3
'๐'.size # => 4
slice
Show source codeHide source code
fn pub slice(start: Int, size: Int) -> ByteArray {
let bytes = ByteArray.new
slice_into(bytes, start, size)
bytes
}
fn pub slice(start: Int, size: Int) -> ByteArray
Slices self
into a sequence of bytes using a byte range.
Examples
Slicing a string using a valid range:
'๐'.slice(start: 0, size: 4) # => '๐'.to_byte_array
'๐'.slice(start: 0, size: 3) # => "\u{FFFD}".to_byte_array
slice_into
Show source codeHide source code
fn pub slice_into(bytes: mut ByteArray, start: Int, size: Int) {
inko_string_slice_bytes_into(self, bytes, start, size)
}
fn pub slice_into(bytes: mut ByteArray, start: Int, size: Int)
Slices self
into a sequence of bytes using a byte range, appending the
bytes to bytes
argument.
This method is useful if you want to slice a String
into a ByteArray
,
but wish to reuse the same ByteArray
rather than allocating a new one for
each slice. Unless you've determined you indeed need to reuse the same
ByteArray
, you're probably better off using String.slice
instead.
Examples
let bytes = ByteArray.new
'๐'.slice_into(bytes, start: 0, size: 4)
bytes # => '๐'.to_byte_array
split
Show source codeHide source code
fn pub split(separator: String) -> Stream[String] {
let mut offset = 0
Stream.new(fn move {
match byte_index(of: separator, starting_at: offset) {
case Some(at) -> {
let start = offset := at + separator.size
Option.Some(slice(start: start, size: at - start).into_string)
}
case _ if offset < size -> {
# No separator found, but we haven't reached the end of the String
# yet. In this case we return the remaining String.
let at = offset := size
Option.Some(slice(start: at, size: size - at).into_string)
}
case _ -> Option.None
}
})
}
fn pub split(separator: String) -> Stream[String]
Splits self
into an iterator of Strings
, each separated by the given
separator.
Examples
Splitting a String
using a single character as the separator:
let iter = 'foo/bar/baz'.split('/')
iter.next # => Option.Some('foo')
iter.next # => Option.Some('bar')
Splitting a String
using multiple characters as the separator:
let iter = 'foo::bar::baz'.split('::')
iter.next # => Option.Some('foo')
iter.next # => Option.Some('bar')
starts_with?
Show source codeHide source code
fn pub starts_with?(prefix: String) -> Bool {
match byte_index(of: prefix, starting_at: 0) {
case Some(idx) -> idx == 0
case _ -> false
}
}
fn pub starts_with?(prefix: String) -> Bool
Returns true
if self
starts with the given String
.
Examples
Checking if a String
starts with another String
:
'test_starts_with'.starts_with?('test_') # => true
'hello'.starts_with?('test_') # => false
strip_prefix
Show source codeHide source code
fn pub strip_prefix(prefix: String) -> String {
if starts_with?(prefix).false? { return clone }
slice(start: prefix.size, size: size - prefix.size).into_string
}
fn pub strip_prefix(prefix: String) -> String
Returns a new String
without the given prefix.
Examples
'xhellox'.strip_prefix('x') # => 'hellox'
strip_suffix
Show source codeHide source code
fn pub strip_suffix(suffix: String) -> String {
if ends_with?(suffix).false? { return clone }
slice(start: 0, size: size - suffix.size).into_string
}
fn pub strip_suffix(suffix: String) -> String
Returns a new String
without the given suffix.
Examples
'xhellox'.strip_suffix('x') # => 'xhello'
substring
Show source codeHide source code
fn pub substring(start: Int, chars: Int) -> String {
let buff = StringBuffer.new
self.chars.each_with_index(fn (index, char) {
if index >= start and buff.size < chars { buff.push(char) }
})
buff.into_string
}
fn pub substring(start: Int, chars: Int) -> String
Slices self
into a substring, using a range of characters and not
bytes.
Slicing a string allows one to extract a substring by providing a start
position and the number of characters. If the index is out of bounds, an
empty String
is returned.
Examples
'hello_world'.substring(start: 0, chars: 5) # => 'hello'
'hello_world'.substring(start: 0, chars: 100) # => 'hello_world'
to_byte_array
Show source codeHide source code
fn pub to_byte_array -> ByteArray {
inko_string_to_byte_array(_INKO.state, self)
}
fn pub to_byte_array -> ByteArray
to_lower
Show source codeHide source code
fn pub to_lower -> String {
inko_string_to_lower(_INKO.state, self)
}
fn pub to_lower -> String
Returns the lowercase equivalent of the current String
.
Examples
Converting a String
containing only ASCII symbols:
'HELLO'.to_lower # => 'hello'
Converting a String
containing Unicode symbols:
'ร'.to_lower # => 'รค'
Converting a String
containing both ASCII and Unicode symbols:
'Aร'.to_lower # => 'aรค'
to_path
Show source codeHide source code
fn pub to_path -> Path {
Path.new(self)
}
fn pub to_path -> Path
Converts self
to a Path
Examples
'/tmp/test.txt'.to_path # => Path.new('/tmp/test.txt')
to_pointer
Show source codeHide source code
fn pub to_pointer -> Pointer[UInt8] {
@bytes
}
fn pub to_pointer -> Pointer[UInt8]
Returns a raw pointer to the bytes of self
.
This method is meant to be used when passing strings to foreign functions
(i.e. *char
arguments). You should avoid using it for anything else.
to_string
Show source codeHide source code
fn pub to_string -> String {
clone
}
fn pub to_string -> String
Converts self
to a String
.
to_upper
Show source codeHide source code
fn pub to_upper -> String {
inko_string_to_upper(_INKO.state, self)
}
fn pub to_upper -> String
Returns the uppercase equivalent of the current String
.
Examples
Converting a String
containing only ASCII symbols:
'hello'.to_upper # => 'HELLO'
Converting a String
containing Unicode symbols:
'รค'.to_upper # => 'ร'
Converting a String
containing both ASCII and Unicode symbols:
'aรค'.to_upper # => 'Aร'
trim
Show source codeHide source code
fn pub trim -> String {
let max = size
let mut start = 0
let mut end = max - 1
while start < max {
if whitespace?(byte(start)) { start += 1 } else { break }
}
while end >= 0 {
if whitespace?(byte(end)) { end -= 1 } else { break }
}
slice(start: start, size: end + 1 - start).into_string
}
fn pub trim -> String
Returns a new String
with both leading and trailing whitespace removed.
Examples
' hello '.trim # => 'hello'
" hello\t".trim # => 'hello'
trim_end
Show source codeHide source code
fn pub trim_end -> String {
let mut index = size - 1
while index >= 0 {
if whitespace?(byte(index)) { index -= 1 } else { break }
}
slice(start: 0, size: index + 1).into_string
}
fn pub trim_end -> String
Returns a new String
without any trailing whitespace.
Examples
'hello '.trim_end # => 'hello'
"hello\t".trim_end # => 'hello'
trim_start
Show source codeHide source code
fn pub trim_start -> String {
let mut index = 0
let max = size
while index < max {
if whitespace?(byte(index)) { index += 1 } else { break }
}
slice(start: index, size: size - index).into_string
}
fn pub trim_start -> String
Returns a new String
without any leading whitespace.
Examples
' hello'.trim_start # => 'hello'
"\thello".trim_start # => 'hello'
Implemented traits
IntoByteArray
impl IntoByteArray for String
ToByteArray
impl ToByteArray for String
Clone
impl Clone[String] for String
Compare
impl Compare[String] for String
Contains
impl Contains[String] for String
Equal
impl Equal[ref String] for String
Drop
impl Drop for String
Format
impl Format for String
Hash
impl Hash for String
Add
impl Add[String, String] for String
Bytes
impl Bytes for String
IntoString
impl IntoString for String
ToString
impl ToString for String