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.

public define ends_with(end: String): Boolean

Checks if self ends with end.

public define find(needle: String, start: *Integer): 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.

public define format(args: List[$1]): String

This creates a new String by processing self as a format.

Format arguments are specified by {}. When a number is specified, the argument is replaced with the corresponding value. Values are indexed from zero, so {0} is the first value, {1} the second, and so on.

If the format argument is empty {}, an internal value iterator is used instead. The value iterator begins at 0 (the first value), and counts upward.

The internal iterator is not altered by numeric arguments given. As a result, it is possible to mix formatting styles. For example, "{1} {} {0} {}".format(1, 2) is 2 1 1 2.

public 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.

public define is_alnum: Boolean

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

public define is_alpha: Boolean

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

public define is_digit: Boolean

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

public define is_space: Boolean

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

public 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.

public 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.

public define parse_i: Option[Integer]

Attempts to convert self into an Integer. The number can optionally begin with - or +, the latter of which is ignored. Afterward, processing occurs as follows:

If self begins with 0b, it is scanned as a binary value.

If self begins with 0c, it is scanned as an octal value.

If self begins with 0x, it is scanned as a hex value.

In all other cases, self is scanned as a decimal value.

Regardless of format, self is only considered valid if all characters inside of it are scanned. If self contains other characters at the beginning or end (such as whitespace), it is invalid.

If self is valid, this returns a Some containing the scanned value.

Otherwise, None is returned.

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

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

public 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.

public define size: Integer

Return the number of bytes in self. This is equivalent to ByteString.size.

public define slice(start: *Integer, stop: *Integer): 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:

public define split(split_by: *String, max: *Integer): List[String]

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

If limit is negative (the default), there is no limit to the size of the resulting List.

Otherwise, this method will make up to max splits to the data. As an example, a max of zero results in a List of one element (the input) since no splits can be made.

public define starts_with(with: String): Boolean

Checks if self starts with with.

public 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.

public define to_bytestring: ByteString

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

public 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.

public 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.