

Strings¶

Useful functions to manipulate strings, based on similar implementations in other standard libraries.

Functions¶

Chainable

camelCase¶

function dash.camelCase(str) --> string

Convert str to camel-case.

Type

string -> string

Parameters

str - string - a string

Returns

string - a string

Examples

dash.camelCase('Pepperoni Pizza') --> 'pepperoniPizza'

dash.camelCase('--pepperoni-pizza--') --> 'pepperoniPizza'

dash.camelCase('__PEPPERONI_PIZZA') --> 'pepperoniPizza'

Chainable

capitalize¶

function dash.capitalize(str) --> string

Capitalize the first letter of str.

Type

string -> string

Parameters

str - string - a string

Returns

string - a string

Examples

dash.capitalize("hello mould") --> "Hello mould"

charToHex¶

function dash.charToHex(char, format, useBytes) --> string

Converts char into a hex representation

Type

char, string?, boolean? -> string

Parameters

char - char - a char

format - string? - a string (optional) - (optional) a string passed to dash.format which formats the hex value of each of the character's code points.

useBytes - boolean? - a boolean (optional) - (default = false) whether to use the character's bytes, rather than UTF-8 code points.

Returns

string - a string

Examples

dash.charToHex("<") --> "3C"

dash.charToHex("<", "&#{};") --> "&#3C;"

dash.charToHex("😏") --> "1F60F"

dash.charToHex("😏", "0x{}") --> "0x1F60F"

dash.charToHex("🤷🏼‍♀️", "&#x{};") --> "&#x1F937;&#x1F3FC;&#x200D;&#x2640;&#xFE0F;"

dash.charToHex("🤷🏼‍♀️", "%{}", true) --> "%F0%9F%A4%B7%F0%9F%8F%BC%E2%80%8D%E2%99%80%EF%B8%8F"

debug¶

function dash.debug(format, ...) --> string

This function first calls dash.format on the arguments provided and then outputs the response to the debug target, set using dash.setDebug. By default, this function does nothing, allowing developers to leave the calls in the source code if that is beneficial.

Type

string, ... -> string

Parameters

format - string - a string - the format match string

... - ...any - any values

Returns

string - a string

Examples

-- During development:
dash.setDebug()
-- At any point in the code:
dash.debug("Hello {}", game.Players.LocalPlayer)
-->> Hello builderman (for example)

Usage

A common pattern would be to dash.setDebug() to alias to print during local development, and send debug messages to an HTTP server on a production build to allow remote debugging.

See

dash.setDebug

Chainable

decodeHtml¶

function dash.decodeHtml(str) --> string

The inverse of dash.encodeHtml. Converts any HTML entities in str to their corresponding characters.

Type

string -> string

Parameters

str - string - a string

Returns

string - a string

Examples

dash.decodeHtml("&lt;b&gt;&#34;Smashed&quot;&lt;/b&gt; &apos;Avocado&#39; &#x1F60F;") --> [[<b>"Smashed"</b> 'Avocado' 😏]]

Chainable

decodeUrl¶

function dash.decodeUrl(str) --> string

The inverse of dash.encodeUrl. Use this to turn a URL which has been encoded for use in a HTTP request back into its original form.

Type

string -> string

Parameters

str - string - a string

Returns

string - a string

Examples

dash.decodeUrl("https://Egg+Fried%20Rice!?")
--> "https://Egg+Fried Rice!?"

Usage

This method is designed to act like decodeURI in JavaScript.

Chainable

decodeUrlComponent¶

function dash.decodeUrlComponent(str) --> string

The inverse of dash.encodeUrlComponent. Use this to turn a string which has been encoded for use as a component of a url back into its original form.

Type

string -> string

Parameters

str - string - a string

Returns

string - a string

Throws

MalformedInput if str contains characters encoded incorrectly.

Examples

dash.decodeUrlComponent("https%3A%2F%2FEgg%2BFried%20Rice!%3F")
--> "https://Egg+Fried Rice!?"

Usage

This method is designed to act like decodeURIComponent in JavaScript.

Chainable

encodeHtml¶

function dash.encodeHtml(str) --> string

Converts the characters &<>"' in str to their corresponding HTML entities.

Type

string -> string

Parameters

str - string - a string

Returns

string - a string

Examples

dash.encodeHtml([[Pease < Bacon > "Fish" & 'Chips']]) --> "Peas &lt; Bacon &gt; &quot;Fish&quot; &amp; &apos;Chips&apos;"

encodeQueryString¶

function dash.encodeQueryString(query) --> string

Takes a query dictionary of key-value pairs and builds a query string that can be concatenated to the end of a url.

Type

<K,V>(Iterable<K,V> -> string)

Generics

K - any - the primary key type (extends any value)

V - any - the primary value type (extends any value)

Parameters

query - Iterable<K, V> - an Iterable (of the primary key type and the primary value type)

Returns

string - a string

Examples

dash.encodeQueryString({
    time = 11,
    biscuits = "hob nobs",
    chocolatey = true
})) --> "?biscuits=hob+nobs&time=11&chocolatey=true"

Usage

A query string which contains duplicate keys with different values is technically valid, but this function doesn't provide a way to produce them.

Chainable

encodeUrl¶

function dash.encodeUrl(str) --> string

Encodes str for use as a URL, for example when calling an HTTP endpoint.

Note that, unlike this function, HttpService.EncodeUrl actually attempts to encode a string for purposes as a URL component rather than an entire URL, and as such will not produce a valid URL.

Type

string -> string

Parameters

str - string - a string

Returns

string - a string

Examples

dash.encodeUrl("https://example.com/Egg+Fried Rice!?🤷🏼‍♀️")
--> "https://example.com/Egg+Fried%20Rice!?%F0%9F%A4%B7%F0%9F%8F%BC%E2%80%8D%E2%99%80%EF%B8%8F"

Usage

This method is designed to act like encodeURI in JavaScript.

See

dash.encodeUrlComponent

Chainable

encodeUrlComponent¶

function dash.encodeUrlComponent(str) --> string

Encodes str for use in a URL, for example as a query parameter of a call to an HTTP endpoint.

Type

string -> string

Parameters

str - string - a string

Returns

string - a string

Examples

dash.encodeUrlComponent("https://example.com/Egg+Fried Rice!?🤷🏼‍♀️")
--> "https%3A%2F%2Fexample.com%2FEgg%2BFried%20Rice!%3F%F0%9F%A4%B7%F0%9F%8F%BC%E2%80%8D%E2%99%80%EF%B8%8F"

Usage

This method is designed to act like encodeURIComponent in JavaScript.
This is very similar to HttpService.EncodeUrl, but is included for parity and conforms closer to the standard (e.g. EncodeUrl unnecessarily encodes !).

Chainable

endsWith¶

function dash.endsWith(str, suffix) --> bool

Checks if str ends with the string suffix.

Type

string, string -> bool

Parameters

str - string - a string

suffix - string - a string

Returns

bool - a boolean

Examples

dash.endsWith("Fun Roblox Games", "Games") --> true

dash.endsWith("Bad Roblox Memes", "Games") --> false

format¶

function dash.format(format, ...) --> string

Returns the format string with placeholders {...} substituted with readable representations of the subsequent arguments.

This function is a simpler & more powerful version of dash.format, inspired by format! in Rust.

{} formats and prints the next argument using :format() if available, or a suitable default representation depending on its type.
{2} formats and prints the 2nd argument.
{#2} prints the length of the 2nd argument.

Display parameters can be combined after a : in the curly braces. Any format parameters used in dash.format can be used here, along with these extras:

{:?} formats any value using dash.serializeDeep.
{:#?} formats any value using dash.pretty.
{:b} formats a number in its binary representation.

Type

string, ... -> string

Parameters

format - string - a string

... - ...any - any values

Returns

string - a string

Examples

local props = {"teeth", "claws", "whiskers", "tail"}
dash.format("{:?} is in {:#?}", "whiskers", props)
-> '"whiskers" is in {"teeth", "claws", "whiskers", "tail"}'

dash.format("{} in binary is {1:b}", 125) -> "125 in binary is 110100"

dash.format("The time is {:02}:{:02}", 2, 4) -> "The time is 02:04"

dash.format("The color blue is #{:06X}", 255) -> "The color blue is #0000FF"

Usage

Escape { with {{ and } similarly with }}.
See https://developer.roblox.com/articles/Format-String for complete list of formating options and further use cases.

See

formatValue¶

function dash.formatValue(value, displayString) --> string

Format a specific value using the specified displayString.

Type

any, DisplayString -> string

Parameters

value - any - any value

displayString - DisplayString - a DisplayString

Returns

string - a string

Examples

dash.formatValue(255, ":06X") --> 0000FF

See

dash.format - for a full description of valid display strings.

hexToChar¶

function dash.hexToChar(hex) --> char

Generates a character from its hex representation.

Type

str -> char

Parameters

hex - str - a str

Returns

char - a char

Throws

MalformedInput if char is not a valid encoding.

Examples

dash.hexToChar("1F60F") --> "😏"

dash.hexToChar("%1F60F") --> "😏"

dash.hexToChar("#1F60F") --> "😏"

dash.hexToChar("0x1F60F") --> "😏"

Chainable

kebabCase¶

function dash.kebabCase(str) --> string

Convert str to kebab-case, making all letters lowercase.

Type

string -> string

Parameters

str - string - a string

Returns

string - a string

Examples

dash.kebabCase('strongStilton') --> 'strong-stilton'

dash.kebabCase(' Strong Stilton ') --> 'strong-stilton'

dash.kebabCase('__STRONG_STILTON__') --> 'strong-stilton'

Usage

Chain with :upper() if you need an upper kebab-case string.

Chainable

leftPad¶

function dash.leftPad(str, length, prefix) --> string

Makes a string of length from str by repeating characters from prefix at the start of the string.

Type

string, number, string -> string

Parameters

str - string - a string

length - number - a number

prefix - string - a string - (default = " ")

Returns

string - a string

Examples

dash.leftPad("toast", 6) --> " toast"

dash.leftPad("2", 2, "0") --> "02"

dash.leftPad("toast", 10, ":)") --> ":):):toast"

pretty¶

function dash.pretty(value, serializeOptions) --> string

Returns a human-readable string for the given value. The string will be formatted across multiple lines if a descendant element gets longer than 80 characters.

Optionally a table of SerializeOptions can be passed which will pass to the underlying dash.serialize function so you can customise what is displayed.

Type

<T>(T, SerializeOptions<T>? -> string)

Generics

T - any - the primary type (extends any value)

Parameters

value - T - the primary type

serializeOptions - SerializeOptions<T>? - a SerializeOptions (of the primary type) (optional)

Returns

string - a string

Examples

local fox = {
    name = "Mr. Fox",
    color = "red"
}
print(dash.pretty(fox))
-->> {color = "red", name = "Mr. Fox"}

local fox = {
    name = "Mr. Fox",
    color = "red"
}
print(dash.pretty(fox, {omitKeys = {"name"}}))
-->> {color = "red"}

See

dash.serializeDeep for a compact alternative.

Chainable

rightPad¶

function dash.rightPad(str, length, suffix) --> string

Makes a string of length from str by repeating characters from suffix at the end of the string.

Type

string, number, string -> string

Parameters

str - string - a string

length - number - a number

suffix - string - a string - (default = " ")

Returns

string - a string

Examples

dash.rightPad("toast", 6) --> "toast "

dash.rightPad("2", 2, "!") --> "2!"

dash.rightPad("toast", 10, ":)") --> "toast:):):"

setDebug¶

function dash.setDebug(fn) --> void

Hooks up any debug methods to invoke fn. By default, dash.debug does nothing.

Type

<A>(...A -> ())

Generics

A - any - the primary arguments (extends any value)

Parameters

fn - ...A - the primary arguments - (default = print)

Returns

void - nothing

Examples

local postMessage = dash.async(function(message)
    HttpService.PostAsync("https://example.com/log", message)
end
-- During production:
dash.setDebug(postMessage)
-- At any point in the code:
dash.debug("Hello is printed")
-- "Hello is printed" is posted to the server

Usage

Calling dash.setDebug() will simply print all calls to dash.debug with formatted arguments.

See

Chainable

snakeCase¶

function dash.snakeCase(str) --> string

Convert str to snake-case, making all letters uppercase.

Type

string -> string

Parameters

str - string - a string

Returns

string - a string

Examples

dash.snakeCase('sweetChickenCurry') --> 'SWEET_CHICKEN_CURRY'

dash.snakeCase(' Sweet Chicken  Curry ') --> 'SWEET_CHICKEN__CURRY'

dash.snakeCase('--sweet-chicken--curry--') --> 'SWEET_CHICKEN__CURRY'

Usage

Chain with :lower() if you need a lower snake-case string.

Chainable

splitOn¶

function dash.splitOn(str, pattern) --> string[], string[]

Splits str into parts based on a pattern delimiter and returns a table of the parts, followed by a table of the matched delimiters.

Type

string, pattern -> string[], string[]

Parameters

str - string - a string

pattern - pattern - a pattern

Returns

string[], string[] - a tuple (an array (of strings) and an array (of strings))

Examples

dash.splitOn("rice") --> {"r", "i", "c", "e"}, {"", "", "", ""}

dash.splitOn("one.two::flour", "[.:]") --> {"one", "two", "", "flour"}, {".", ":", ":"}

Usage

This method is useful only when you need a pattern as a delimiter.
Use the Roblox native string.split if you are splitting on a simple string.

Chainable

startsWith¶

function dash.startsWith(str, prefix) --> bool

Checks if str starts with the string start.

Type

string, string -> bool

Parameters

str - string - a string

prefix - string - a string

Returns

bool - a boolean

Examples

dash.startsWith("Fun Roblox Games", "Fun") --> true

dash.startsWith("Chess", "Fun") --> false

Chainable

titleCase¶

function dash.titleCase(str) --> string

Convert str to title-case, where the first letter of each word is capitalized.

Type

string -> string

Parameters

str - string - a string

Returns

string - a string

Examples

dash.titleCase("jello world") --> "Jello World"

dash.titleCase("yellow-jello with_sprinkles") --> "Yellow-jello With_sprinkles"

dash.titleCase("yellow jello's don’t mellow") --> "Yellow Jello's Dont’t Mellow"

Usage

Dashes, underscores and apostraphes don't break words.

Chainable

trim¶

function dash.trim(str) --> string

Removes any spaces from the start and end of str.

Type

string -> string

Parameters

str - string - a string

Returns

string - a string

Examples

dash.trim("  roast veg  ") --> "roast veg"