Search results

There are no results.

std.string.String

Atomic
class pub builtin String

An UTF-8 encoded and immutable string type.

Static methods

from_pointer

Show source code
Hide 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 code
Hide 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 code
Hide 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 code
Hide 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 code
Hide 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 code
Hide 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 code
Hide 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 code
Hide 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 code
Hide 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 code
Hide 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 code
Hide 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 code
Hide 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 code
Hide 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 code
Hide source code
fn pub clone -> String {
  self
}
fn pub clone -> String

Creates a clone of self.

cmp

Show source code
Hide 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 code
Hide 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 code
Hide 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 code
Hide 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 code
Hide 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:

  1. Double quotes
  2. Tabs
  3. Newlines
  4. Carriage returns
  5. Backspace
  6. Form feed
  7. Backslash

Examples

"hello\nworld" # => 'hello\nworld'
"hello\\world" # => 'hello\\world'

fmt

Show source code
Hide 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 code
Hide 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 code
Hide source code
fn pub move into_byte_array -> ByteArray {
  to_byte_array
}
fn pub move into_byte_array -> ByteArray

into_string

Show source code
Hide source code
fn pub move into_string -> String {
  self
}
fn pub move into_string -> String

Moves self into a String.

pad_end

Show source code
Hide 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 code
Hide 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 code
Hide 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 code
Hide 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 code
Hide 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 code
Hide 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 code
Hide 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 code
Hide 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 code
Hide 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 code
Hide 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 code
Hide 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 code
Hide 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 code
Hide 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 code
Hide 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 code
Hide 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 code
Hide 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 code
Hide source code
fn pub to_string -> String {
  clone
}
fn pub to_string -> String

Converts self to a String.

to_upper

Show source code
Hide 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 code
Hide 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 code
Hide 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 code
Hide 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

std.byte_array.

IntoByteArray

impl IntoByteArray for String
std.byte_array.

ToByteArray

impl ToByteArray for String
std.clone.

Clone

impl Clone[String] for String
std.cmp.

Compare

impl Compare[String] for String
std.cmp.

Contains

impl Contains[String] for String
std.cmp.

Equal

impl Equal[ref String] for String
std.drop.

Drop

impl Drop for String
std.fmt.

Format

impl Format for String
std.hash.

Hash

impl Hash for String
std.ops.

Add

impl Add[String, String] for String
std.string.

Bytes

impl Bytes for String
std.string.

IntoString

impl IntoString for String
std.string.

ToString

impl ToString for String