README.md

String & slice utility library for Solidity

Overview

Functionality in this library is largely implemented using an abstraction called a 'slice'. A slice represents a part of a string - anything from the entire string to a single character, or even no characters at all (a 0-length slice). Since a slice only has to specify an offset and a length, copying and manipulating slices is a lot less expensive than copying and manipulating the strings they reference.

To further reduce gas costs, most functions on slice that need to return a slice modify the original one instead of allocating a new one; for instance, s.split(".") will return the text up to the first '.', modifying s to only contain the remainder of the string after the '.'. In situations where you do not want to modify the original slice, you can make a copy first with .copy(), for example: s.copy().split("."). Try and avoid using this idiom in loops; since Solidity has no memory management, it will result in allocating many short-lived slices that are later discarded.

Functions that return two slices come in two versions: a non-allocating version that takes the second slice as an argument, modifying it in place, and an allocating version that allocates and returns the second slice; see nextRune for example.

Functions that have to copy string data will return strings rather than slices; these can be cast back to slices for further processing if required.

Examples

Basic usage

import "github.com/Arachnid/solidity-stringutils/strings.sol";

contract Contract {
    using strings for *;

    // ...
}

Getting the character length of a string

var len = "Unicode snowman ☃".toSlice().len(); // 17

Splitting a string around a delimiter

var s = "foo bar baz".toSlice();
var foo = s.split(" ".toSlice());

After the above code executes, s is now "bar baz", and foo is now "foo".

Splitting a string into an array

var s = "www.google.com".toSlice();
var delim = ".".toSlice();
var parts = new string[](s.count(delim) + 1);
for(uint i = 0; i < parts.length; i++) {
    parts[i] = s.split(delim).toString();
}

Extracting the middle part of a string

var s = "www.google.com".toSlice();
strings.slice memory part;
s.split(".".toSlice(), part); // part and return value is "www"
s.split(".".toSlice(), part); // part and return value is "google"

This approach uses less memory than the above, by reusing the slice part for each section of string extracted.

Converting a slice back to a string

var myString = mySlice.toString();

Finding and returning the first occurrence of a substring

var s = "A B C B D".toSlice();
s.find("B".toSlice()); // "B C B D"

find modifies s to contain the part of the string from the first match onwards.

Finding and returning the last occurrence of a substring

var s = "A B C B D".toSlice();
s.rfind("B".toSlice()); // "A B C B"

rfind modifies s to contain the part of the string from the last match back to the start.

Finding without modifying the original slice.

var s = "A B C B D".toSlice();
var substring = s.copy().rfind("B".toSlice()); // "A B C B"

copy lets you cheaply duplicate a slice so you don't modify the original.

Prefix and suffix matching

var s = "A B C B D".toSlice();
s.startsWith("A".toSlice()); // True
s.endsWith("D".toSlice()); // True
s.startsWith("B".toSlice()); // False

Removing a prefix or suffix

var s = "A B C B D".toSlice();
s.beyond("A ".toSlice()).until(" D".toSlice()); // "B C B"

beyond modifies s to contain the text after its argument; until modifies s to contain the text up to its argument. If the argument isn't found, s is unmodified.

Finding and returning the string up to the first match

var s = "A B C B D".toSlice();
var needle = "B".toSlice();
var substring = s.until(s.copy().find(needle).beyond(needle));

Calling find on a copy of s returns the part of the string from needle onwards; calling .beyond(needle) removes needle as a prefix, and finally calling s.until() removes the entire end of the string, leaving everything up to and including the first match.

Concatenating strings

var s = "abc".toSlice().concat("def".toSlice()); // "abcdef"

Reference

toSlice(string self) internal returns (slice)

Returns a slice containing the entire string.

Arguments:

• self The string to make a slice from.

Returns A newly allocated slice containing the entire string.

copy(slice self) internal returns (slice)

Returns a new slice containing the same data as the current slice.

Arguments:

• self The slice to copy.

Returns A new slice containing the same data as self.

toString(slice self) internal returns (string)

Copies a slice to a new string.

Arguments:

• self The slice to copy.

Returns A newly allocated string containing the slice's text.

len(slice self) internal returns (uint)

Returns the length in runes of the slice. Note that this operation takes time proportional to the length of the slice; avoid using it in loops, and call slice.empty() if you only need to know whether the slice is empty or not.

Arguments:

• self The slice to operate on.

Returns The length of the slice in runes.

empty(slice self) internal returns (bool)

Returns true if the slice is empty (has a length of 0).

Arguments:

• self The slice to operate on.

Returns True if the slice is empty, False otherwise.

compare(slice self, slice other) internal returns (int)

Returns a positive number if other comes lexicographically after self, a negative number if it comes before, or zero if the contents of the two slices are equal. Comparison is done per-rune, on unicode codepoints.

Arguments:

• self The first slice to compare.
• other The second slice to compare.

Returns The result of the comparison.

equals(slice self, slice other) internal returns (bool)

Returns true if the two slices contain the same text.

Arguments:

• self The first slice to compare.
• self The second slice to compare.

Returns True if the slices are equal, false otherwise.

nextRune(slice self, slice rune) internal returns (slice)

Extracts the first rune in the slice into rune, advancing the slice to point to the next rune and returning self.

Arguments:

• self The slice to operate on.
• rune The slice that will contain the first rune.

Returns rune.

nextRune(slice self) internal returns (slice ret)

Returns the first rune in the slice, advancing the slice to point to the next rune.

Arguments:

• self The slice to operate on.

Returns A slice containing only the first rune from self.

ord(slice self) internal returns (uint ret)

Returns the number of the first codepoint in the slice.

Arguments:

• self The slice to operate on.

Returns The number of the first codepoint in the slice.

keccak(slice self) internal returns (bytes32 ret)

Returns the keccak-256 hash of the slice.

Arguments:

• self The slice to hash.

Returns The hash of the slice.

startsWith(slice self, slice needle) internal returns (bool)

Returns true if self starts with needle.

Arguments:

• self The slice to operate on.
• needle The slice to search for.

Returns True if the slice starts with the provided text, false otherwise.

beyond(slice self, slice needle) internal returns (slice)

If self starts with needle, needle is removed from the beginning of self. Otherwise, self is unmodified.

Arguments:

• self The slice to operate on.
• needle The slice to search for.

Returns self

endsWith(slice self, slice needle) internal returns (bool)

Returns true if the slice ends with needle.

Arguments:

• self The slice to operate on.
• needle The slice to search for.

Returns True if the slice starts with the provided text, false otherwise.

until(slice self, slice needle) internal returns (slice)

If self ends with needle, needle is removed from the end of self. Otherwise, self is unmodified.

Arguments:

• self The slice to operate on.
• needle The slice to search for.

Returns self

find(slice self, slice needle) internal returns (slice)

Modifies self to contain everything from the first occurrence of needle to the end of the slice. self is set to the empty slice if needle is not found.

Arguments:

• self The slice to search and modify.
• needle The text to search for.

Returns self.

rfind(slice self, slice needle) internal returns (slice)

Modifies self to contain the part of the string from the start of self to the end of the first occurrence of needle. If needle is not found, self is set to the empty slice.

Arguments:

• self The slice to search and modify.
• needle The text to search for.

Returns self.

split(slice self, slice needle, slice token) internal returns (slice)

Splits the slice, setting self to everything after the first occurrence of needle, and token to everything before it. If needle does not occur in self, self is set to the empty slice, and token is set to the entirety of self.

Arguments:

• self The slice to split.
• needle The text to search for in self.
• token An output parameter to which the first token is written.

Returns token.

split(slice self, slice needle) internal returns (slice token)

Splits the slice, setting self to everything after the first occurrence of needle, and returning everything before it. If needle does not occur in self, self is set to the empty slice, and the entirety of self is returned.

Arguments:

• self The slice to split.
• needle The text to search for in self.

Returns The part of self up to the first occurrence of delim.

rsplit(slice self, slice needle, slice token) internal returns (slice)

Splits the slice, setting self to everything before the last occurrence of needle, and token to everything after it. If needle does not occur in self, self is set to the empty slice, and token is set to the entirety of self.

Arguments:

• self The slice to split.
• needle The text to search for in self.
• token An output parameter to which the first token is written.

Returns token.

rsplit(slice self, slice needle) internal returns (slice token)

Splits the slice, setting self to everything before the last occurrence of needle, and returning everything after it. If needle does not occur in self, self is set to the empty slice, and the entirety of self is returned.

Arguments:

• self The slice to split.
• needle The text to search for in self.

Returns The part of self after the last occurrence of delim.

count(slice self, slice needle) internal returns (uint count)

Counts the number of nonoverlapping occurrences of needle in self.

Arguments:

• self The slice to search.
• needle The text to search for in self.

Returns The number of occurrences of needle found in self.

contains(slice self, slice needle) internal returns (bool)

Returns True if self contains needle.

Arguments:

• self The slice to search.
• needle The text to search for in self.

Returns True if needle is found in self, false otherwise.

concat(slice self, slice other) internal returns (string)

Returns a newly allocated string containing the concatenation of self and other.

Arguments:

• self The first slice to concatenate.
• other The second slice to concatenate.

Returns The concatenation of the two strings.

join(slice self, slice[] parts) internal returns (string)

Joins an array of slices, using self as a delimiter, returning a newly allocated string.

Arguments:

• self The delimiter to use.
• parts A list of slices to join.

Returns A newly allocated string containing all the slices in parts, joined with self.