Class String

(builtin) class String {  }

The String class provides a wrapper over a C char *. The String class is guaranteed to have a single '\0' terminator. Additionally, a String is guaranteed to always be valid utf-8.

The methods on the String class treat the underlying String as being immutable, and thus always create a new String instead of modifying the existing one.

Methods

define format(args: $1...): String

This creates a new String by processing self as a format. Format specifiers must be between braces ({}), and must be between 0 and 99. Each format specifier is replaced with the according argument, with the first argument being at 0, the second at 1, and so on.

This function is a useful alternative to interpolation for situations where the value is a long expression, or where a single value is to be repeated several times.

  • ValueError if a format specifier is malformed or has too many digits.
  • IndexError if the format specifier specifies an out-of-range argument.

define ends_with(end: String): Boolean

Checks if self ends with end.

define find(needle: String, start: *Integer = 0): Option[Integer]

Check for needle being within self. By default, this begins at the start of self. If start is non-zero, then the search begins start bytes away from the beginning of self. If start lies within the middle of a utf-8 codepoint, then None is automatically returned.

If needle is found, the result is a Some holding the index.

Otherwise, this returns None.

define html_encode: String

Check for one of "&", "<", or ">" being within self.

If found, a new String is contained with any instance of the above being replaced by an html-safe value.

If not found, self is returned.

define is_alnum: Boolean

Return true if self has only alphanumeric([a-zA-Z0-9]+) characters, false otherwise.

define is_alpha: Boolean

Return true if self has only alphabetical([a-zA-Z]+) characters, false otherwise.

define is_digit: Boolean

Return true if self has only digit([0-9]+) characters, false otherwise.

define is_space: Boolean

Returns true if self has only space(" \t\r\n") characters, false otherwise.

define lower: String

Checks if any characters within self are within [A-Z]. If so, it creates a new String with [A-Z] replaced by [a-z]. Otherwise, self is returned.

define lstrip(to_strip: String): String

This walks through self from left to right, stopping on the first utf-8 chunk that is not found within to_strip. The result is a newly-made copy of self without the elements within to_strip at the front.

define parse_i: Option[Integer]

Attempts to convert self into an Integer. Currently, self is parsed as a base-10 encoded value.

If the value is a valid Integer, then a Some containing the value is returned.

Otherwise, None is returned.

define replace(needle: String, new: String): String

Create a new String consisting of every needle replaced with new.

define rstrip(to_strip: String): String

This walks through self from right to left, stopping on the first utf-8 chunk that is not found within to_strip. The result is a newly-made copy of self without the elements of to_strip at the end.

define slice(start: *Integer = 0, stop: *Integer = -1): String

Create a new String copying a section of self from start to stop. This function works using byte indexes into the String value.

If a negative index is given, it is treated as an offset from the end of self, with -1 being considered the last element.

On error, this generates an empty String. Error conditions are:

  • Either start or stop is out of range.
  • The resulting slice would not be valid utf-8.
  • The start is larger than the stop (reversed).

define split(split_by: *String = " "): List[String]

This attempts to split self using split_by, with a default value of a single space.

  • ValueError if split_by is empty.

define starts_with(with: String): Boolean

Checks if self starts with with.

define strip(to_strip: String): String

This walks through self from right to left, and then from left to right. The result of this is a newly-made String without any elements within to_strip at either end.

define to_bytestring: ByteString

Produce a copy of self, as a ByteString. This allows per-Byte operations to be performed.

define trim: String

Checks if self starts or ends with any of " \t\r\n". If it does, then a new String is made with spaces removed from both sides. If it does not, then this returns self.

define upper: String

Checks if any characters within self are within [a-z]. If so, it creates a new String with [a-z] replaced by [A-Z]. Otherwise, self is returned.