ESC
No recent searches
Search by
Standard Library  /  String

Grain Docs

Welcome to Grain! Editor Setup Getting Grain

The Guide

Hello World The Basics Conditionals Functions Shadowing and Mutation Loops Lists and arrays Custom Data Types Modules Pattern Matching

Reference

Building for Production Built-in Types The Grain CLI Graindoc

Standard Library

Pervasives BigInt Array Buffer Bytes Char Exception Float32 Float64 Hash Int16 Int32 Int64 Int8 Json List Map Marshal Number Option Path PriorityQueue Queue Random Range Rational Regex Result Stack Set String Uint16 Uint32 Uint64 Uint8 Uri wasi / File wasi / Process wasi / Random wasi / Time

String

Utilities for working with strings.

Edit on GitHub
Added in 0.2.0
versionchanges
0.1.0Originally named `strings`
0.2.0Renamed to `string`
 
from "string" include String

Types

Type declarations included in the String module.

String.Encoding

enum Encoding {
  UTF8,
  UTF16_BE,
  UTF16_LE,
  UTF32_BE,
  UTF32_LE,
}

Byte encodings

Values

Functions and constants included in the String module.

String.concat

Added in 0.2.0 No other changes yet. 
concat : (str1: String, str2: String) => String

Concatenate two strings.

Parameters:

str1: The beginning string
str2: The ending string

Returns:

String: The combined string

Examples:

String.concat("Foo", "Bar") == "FooBar"

String.length

Added in 0.1.0 No other changes yet. 
length : (string: String) => Number

Returns the character length of the input string.

Parameters:

string: The string to inspect

Returns:

Number: The number of characters in the string

Examples:

String.length("Hello world") == 11

String.byteLength

Added in 0.1.0 No other changes yet. 
byteLength : (string: String) => Number

Returns the byte length of the input string.

Parameters:

string: The string to inspect

Returns:

Number: The number of bytes in the string

Examples:

String.byteLength("🌾") == 4

String.isEmpty

Added in 0.6.0 No other changes yet. 
isEmpty : (string: String) => Bool

Determines if the string contains no characters.

Parameters:

string: The string to inspect

Returns:

Bool: true if the string is empty and false otherwise

String.indexOf

Added in 0.3.0 No other changes yet. 
indexOf : (search: String, string: String) => Option<Number>

Finds the first position of a substring in the input string.

Parameters:

search: The substring to find
string: The string to inspect

Returns:

Option<Number>: Some(position) containing the starting position of the substring if found or None otherwise

Examples:

String.indexOf("world", "Hello world") == Some(6)

String.lastIndexOf

Added in 0.5.3 No other changes yet. 
lastIndexOf : (search: String, string: String) => Option<Number>

Finds the last position of a substring in the input string.

Parameters:

search: The substring to find
string: The string to inspect

Returns:

Option<Number>: Some(position) containing the starting position of the substring if found or None otherwise

Examples:

String.lastIndexOf("world", "Hello world world") == Some(12)

String.charCodeAt

Added in 0.5.3 No other changes yet. 
charCodeAt : (position: Number, string: String) => Number

Get the Unicode code point at the position in the input string.

Parameters:

position: The position to check
string: The string to search

Returns:

Number: The character code at the provided position

Throws:

Failure(String)

  • When the position is out of bounds

MalformedUnicode

  • When the string is malformed

Examples:

String.charCodeAt(5, "Hello world") == 32

String.charAt

Added in 0.4.0 No other changes yet. 
charAt : (position: Number, string: String) => Char

Get the character at the position in the input string.

Parameters:

position: The position to check
string: The string to search

Returns:

Char: The character at the provided position

Throws:

Failure(String)

  • When the position is out of bounds

MalformedUnicode

  • When the string is malformed

Examples:

String.charAt(5, "Hello world") == ' '

String.explode

Added in 0.3.0 No other changes yet. 
explode : (string: String) => Array<Char>

Split a string into its Unicode characters.

Parameters:

string: The string to split

Returns:

Array<Char>: An array containing all characters in the string

Throws:

MalformedUnicode

  • When the string is malformed

Examples:

String.explode("Hello") == [> 'H', 'e', 'l', 'l', 'o']

String.implode

Added in 0.3.0 No other changes yet. 
implode : (arr: Array<Char>) => String

Create a string from an array of characters.

Parameters:

arr: The array to combine

Returns:

String: A string representation of the array of characters

Examples:

String.implode([> 'H', 'e', 'l', 'l', 'o']) == "Hello"

String.reverse

Added in 0.4.5 No other changes yet. 
reverse : (string: String) => String

Create a string that is the given string reversed.

Parameters:

string: The string to reverse

Returns:

String: A string whose characters are in the reverse order of the given string

Examples:

String.reverse("olleH") == "Hello"

String.split

split : (separator: String, string: String) => Array<String>

Split a string by the given separator.

Parameters:

separator: The separator to split on
string: The string to split

Returns:

Array<String>: An array of substrings from the initial string

Throws:

MalformedUnicode

  • When the string is malformed

Examples:

String.split(" ", "Hello world") == [> "Hello", "world"]

String.slice

Added in 0.1.0
versionchanges
0.6.0Default `end` to the String length
 
slice : (start: Number, ?end: Number, string: String) => String

Get a portion of a string.

Parameters:

start: The start position of the substring
?end: The end position of the substring, exclusive
string: The input string

Returns:

String: The substring from the initial string

Throws:

IndexOutOfBounds

  • When start is out of bounds
  • When end is out of bounds

InvalidArgument(String)

  • When the start index is not an integer
  • When the to index is not an integer
  • When start is greater than end

Examples:

String.slice(0, end=5, "Hello world") == "Hello"
String.slice(0, "Hello world") == "Hello world"

String.contains

Added in 0.1.0 No other changes yet. 
contains : (search: String, string: String) => Bool

Check if a string contains a substring.

Parameters:

search: The substring to check
string: The string to search

Returns:

Bool: true if the input string contains the search value or false otherwise

Examples:

String.contains("world", "Hello world") == true

String.startsWith

Added in 0.1.0 No other changes yet. 
startsWith : (search: String, string: String) => Bool

Check if a string begins with another string.

Parameters:

search: The string to compare to the start
string: The string to search

Returns:

Bool: true if the input string starts with the search value or false otherwise

Examples:

String.startsWith("Hello", "Hello world") == true

String.endsWith

Added in 0.1.0 No other changes yet. 
endsWith : (search: String, string: String) => Bool

Check if a string ends with another string.

Parameters:

search: The string to compare to the end
string: The string to search

Returns:

Bool: true if the input string ends with the search value or false otherwise

Examples:

String.endsWith("world", "Hello world") == true

String.replaceFirst

Added in 0.5.4 No other changes yet. 
replaceFirst :
  (searchPattern: String, replacement: String, string: String) => String

Replaces the first appearance of the search pattern in the string with the replacement value.

Parameters:

searchPattern: The string to replace
replacement: The replacement
string: The string to change

Returns:

String: A new string with the first occurrence of the search pattern replaced

Examples:

String.replaceFirst("🌾", "🌎", "Hello 🌾🌾") == "Hello 🌎🌾"

String.replaceLast

Added in 0.5.4 No other changes yet. 
replaceLast :
  (searchPattern: String, replacement: String, string: String) => String

Replaces the last appearance of the search pattern in the string with the replacement value.

Parameters:

searchPattern: The string to replace
replacement: The replacement
string: The string to change

Returns:

String: A new string with the last occurrence of the search pattern replaced

Examples:

String.replaceLast("🌾", "🌎", "Hello 🌾🌾") == "Hello 🌾🌎"

String.replaceAll

Added in 0.5.4 No other changes yet. 
replaceAll :
  (searchPattern: String, replacement: String, string: String) => String

Replaces every appearance of the search pattern in the string with the replacement value.

Parameters:

searchPattern: The string to replace
replacement: The replacement
string: The string to change

Returns:

String: A new string with each occurrence of the search pattern replaced

Examples:

String.replaceAll("🌾", "🌎", "Hello 🌾🌾") == "Hello 🌎🌎"

String.encodeAt

Added in 0.4.0
versionchanges
0.6.0Added `includeBom` default argument
 
encodeAt :
  (string: String, encoding: Encoding, dest: Bytes, destPos: Number,
   ?includeBom: Bool) => Bytes

Encodes the given string into a byte sequence at the supplied position using the encoding scheme provided.

Parameters:

string: The input string
encoding: The encoding to use
dest: The byte sequence that will be copied
destPos: The location in the byte sequence to write the output
?includeBom: Whether or not to include a byte order marker (false by default)

Returns:

Bytes: A copy of the input bytes with the encoded string replaced at the given position

Throws:

InvalidArgument(String)

  • When destPos is not an integer
  • When destPos is negative

String.encode

Added in 0.4.0
versionchanges
0.6.0Added `includeBom` default argument
 
encode : (string: String, encoding: Encoding, ?includeBom: Bool) => Bytes

Encodes the given string using the given encoding scheme.

Parameters:

string: The input string
encoding: The encoding to use
?includeBom: Whether or not to include a byte order marker (false by default)

Returns:

Bytes: The byte representation of the string in the given encoding

String.decodeRange

Added in 0.4.0
versionchanges
0.6.0Added `keepBom` default argument
 
decodeRange :
  (bytes: Bytes, encoding: Encoding, start: Number, size: Number,
   ?keepBom: Bool) => String

Decodes the given byte sequence of the specified range into a string using the encoding scheme provided.

Parameters:

bytes: The input bytes
encoding: The encoding to use
start: The byte offset to begin decoding from
size: The maximum number of bytes to decode
?keepBom: Whether or not to include a byte order marker (false by default)

Returns:

String: The decoded string

Throws:

InvalidArgument(String)

  • When start is not an integer
  • When start is negative
  • When size is not an integer
  • When size is negative

String.decode

Added in 0.4.0
versionchanges
0.6.0Added `keepBom` default argument
 
decode : (bytes: Bytes, encoding: Encoding, ?keepBom: Bool) => String

Decodes the given byte sequence into a string using the given encoding scheme.

Parameters:

bytes: The input bytes
encoding: The encoding to use
?keepBom: Whether or not to include a byte order marker (false by default)

Returns:

String: The decoded string

String.forEachCodePoint

Added in 0.4.0 No other changes yet. 
forEachCodePoint : (fn: (Number => Void), str: String) => Void

Iterates over Unicode code points in a string.

Parameters:

fn: The iterator function
str: The string to iterate

Examples:

String.forEachCodePoint(print, "Hello world")

String.forEachCodePointi

Added in 0.4.0 No other changes yet. 
forEachCodePointi : (fn: ((Number, Number) => Void), str: String) => Void

Iterates over Unicode code points in a string. This is the same as forEachCodePoint, but provides the code point’s index in the string as the second argument to the iterator function.

Parameters:

fn: The iterator function
str: The string to iterate

Examples:

String.forEachCodePointi((codepoint, index) => print((codepoint, index)), "Hello world")

String.forEachChar

Added in 0.6.5 No other changes yet. 
forEachChar : (fn: (Char => Void), str: String) => Void

Iterates over Unicode characters in a string.

Parameters:

fn: The iterator function
str: The string to iterate

Examples:

String.forEachChar(print, "Hello world")

String.forEachChari

Added in 0.6.5 No other changes yet. 
forEachChari : (fn: ((Char, Number) => Void), str: String) => Void

Iterates over Unicode characters in a string. This is the same as forEachChar, but provides the characters’s index in the string as the second argument to the iterator function.

Parameters:

fn: The iterator function
str: The string to iterate

Examples:

String.forEachChari((char, index) => print((char, index)), "Hello world")

String.map

Added in 0.6.5 No other changes yet. 
map : (fn: (Char => Char), str: String) => String

Builds a new string by mapping Unicode characters.

Parameters:

fn: The mapping function
str: The string to map

Examples:

assert String.map((c) => 'a', "Hello world") == "aaaaaaaaaaa"

String.mapi

Added in 0.6.5 No other changes yet. 
mapi : (fn: ((Char, Number) => Char), str: String) => String

Builds a new string by mapping Unicode characters. This is the same as mapChar, but provides the characters’s index in the string as the second argument to the mapping function.

Parameters:

fn: The mapping function
str: The string to map

Examples:

assert String.mapi((char, index) => String.charAt(0, toString(index)), "Hello world") == "01234567891"

String.trimStart

Added in 0.4.2 No other changes yet. 
trimStart : (string: String) => String

Trims the beginning of a string—removing any leading whitespace characters.

Parameters:

string: The string to be trimmed

Returns:

String: The trimmed string

Examples:

String.trimStart("   Hello World") == "Hello World"

String.trimEnd

Added in 0.4.2 No other changes yet. 
trimEnd : (string: String) => String

Trims the end of a string—removing any trailing whitespace characters.

Parameters:

string: The string to be trimmed

Returns:

String: The trimmed string

Examples:

String.trimEnd("Hello World   ") == "Hello World"

String.trim

Added in 0.4.2 No other changes yet. 
trim : (string: String) => String

Trims a string—removing all leading and trailing whitespace characters.

Parameters:

string: The string to be trimmed

Returns:

String: The trimmed string

Examples:

String.trim("   Hello World   ") == "Hello World"

String.toAsciiLowercase

Added in 0.6.0 No other changes yet. 
toAsciiLowercase : (string: String) => String

Converts all ASCII uppercase characters in the string to lowercase.

Parameters:

string: The string to convert

Returns:

String: The lowercased string

Examples:

assert String.toAsciiLowercase("aBc123") == "abc123"

String.toAsciiUppercase

Added in 0.6.0 No other changes yet. 
toAsciiUppercase : (string: String) => String

Converts all ASCII lowercase characters in the string to uppercase.

Parameters:

string: The string to convert

Returns:

String: The uppercased string

Examples:

assert String.toAsciiUppercase("aBc123") == "ABC123"
Set Uint16

Sign up for farm-to-inbox developer news

You can unsubscribe at any time. Read our privacy policy.

Copyright © 2024 The Grain Programming Language