string

The number of characters of a text.

#s gives the same and is shorter to write. A common use is centring a title on the screen:

print(string.len("Andesite"), #"Andesite", #"")
local title = "IRON FARM"
local width = term.get_size().w
print(string.rep(" ", math.floor((width - #title) / 2)) .. title)

8   8   0
                     IRON FARM

See also string.sub()

Converts the text to capitals.

Letters with accents follow: é becomes É. Other characters stay as they are.

local name = "brass casing"
print(name:upper())
print(string.upper("Gate 3: open"))

BRASS CASING
GATE 3: OPEN

See also string.lower()

Converts the text to small letters.

Comparing texts is exact: "Yes" ~= "yes". Bring what a player typed to small letters before comparing it, so that YES, Yes and yes all work:

local function is_yes(answer)
  local a = answer:trim():lower()
  return a == "yes" or a == "y"
end
print(is_yes("YES"), is_yes("  y "), is_yes("no"))

true    true    false

In a program: write("Open the gate? ") if is_yes(read()) then ... end.

See also string.upper() string.trim()

The part of the text from position i to position j, both included.

local s = "Mechanical Press"
print(s:sub(1, 10))
print(s:sub(12))
print(s:sub(-5))
print(s:sub(-5, -3))

Mechanical
Press
Press
Pre

It never fails on positions out of the text: a start before the first character starts at the first one, an end past the last character stops at the last one, and a start after the end gives "". Positions must be whole numbers (bad argument #2 to 'sub' (number has no integer representation)).

local s = "Saw"
print("[" .. s:sub(0, 2) .. "]", "[" .. s:sub(2, 99) .. "]", "[" .. s:sub(5) .. "]")

[Sa]    [aw]    []

To fit a name in a column, cut it and mark the cut:

local function fit(name, width)
  if #name > width then
    return name:sub(1, width - 1) .. "~"
  end
  return name
end
print(fit("Andesite Alloy", 10))
print(fit("Zinc", 10))

Andesite ~
Zinc

See also string.find() string.split()

Position of a text inside another, or nil.

The search is plain: every character means itself. Lua's patterns do not exist in Brass, so ., %, [ or ( have no special meaning (in Lua, ("v1.2"):find(".") finds any character, here it finds the dot). There is no string.match, gmatch or gsub either: find, sub and split do the same jobs. A fourth argument (the "plain" flag of Lua) is accepted and ignored.

Only the start position comes back. The match ends at start + #text - 1. The search is case sensitive: lower both texts first to ignore case.

print(("v1.2"):find("."))
print(("Iron Ingot"):find("Ingot"), ("Iron Ingot"):find("ingot"))
local id = "create:brass_ingot"
local colon = id:find(":")
print(id:sub(1, colon - 1), id:sub(colon + 1))

3
6   nil
create  brass_ingot

init starts the search further on, which lets you find every occurrence. A start past the end gives nil:

local log = "jam at press; ok; jam at saw; ok"
local count, from = 0, 1
while true do
  local at = log:find("jam", from)
  if at == nil then
    break
  end
  count = count + 1
  from = at + 1
end
print("jams: " .. count)

jams: 2

See also string.sub() string.starts() string.split()

True if the text starts with prefix.

A Brass extension (Lua has none). Exact, case sensitive, and an empty prefix is always found. Handy to sort item ids by mod, or commands by their first word:

local items = {"create:brass_ingot", "minecraft:iron_ingot", "create:zinc_ingot"}
for _, id in ipairs(items) do
  if id:starts("create:") then
    print(id)
  end
end

create:brass_ingot
create:zinc_ingot

See also string.ends() string.find()

True if the text ends with suffix.

A Brass extension, like string.starts. Use it for families of items or for file names:

local ids = {"minecraft:iron_ingot", "minecraft:iron_nugget", "create:zinc_ingot"}
local ingots = 0
for _, id in ipairs(ids) do
  if id:ends("_ingot") then
    ingots = ingots + 1
  end
end
print(ingots .. " kinds of ingot")
print(("report.log"):ends(".log"), ("report.log"):ends(""))

2 kinds of ingot
true    true

See also string.starts()

The text repeated n times, with an optional separator between the copies.

print(string.rep("=", 20))
print(("ab"):rep(3, ", "))
print("[" .. ("x"):rep(0) .. "]")

====================
ab, ab, ab
[]

n must be a whole number. A result over 65536 characters stops with string too long.

A progress bar made of characters: the filled part, then the empty part, always the same width.

local function bar(value, max, width)
  local filled = math.min(width, math.round(value / max * width))
  return "[" .. string.rep("#", filled) .. string.rep("-", width - filled) .. "]"
end
print(bar(750, 1000, 20) .. " 75%")
print(bar(0, 1000, 20))
print(bar(1200, 1000, 20) .. " full")

[###############-----] 75%
[--------------------]
[####################] full

See also string.format()

The text backwards.

A train line written as one letter per station is visited backwards on the return trip:

local route = "MSFD"   -- Mine, Smeltery, Factory, Depot
print("Outward: " .. route)
print("Return:  " .. route:reverse())

Outward: MSFD
Return:  DFSM

See also string.sub()

Builds a text from a model and values: "%d items", "%.2f", "%5s"...

Each % code of the model is replaced by the next value, written the way the code says:

Between the % and the letter, in this order, you can add:

• flags: - pads on the right (the value goes left), 0 pads numbers with zeros, + always shows the sign of a number, a space puts a space where a positive number has no sign.
• a width, one or two digits: the least number of characters, padded with spaces on the left. %5d writes 42 as 42.
• a precision, a dot and digits: the number of decimals for %f, the most characters kept for %s (%.3s cuts Andesite to And). %d and %x ignore it.

print(string.format("%d items in %d chests", 1250, 20))
print(string.format("Speed: %.1f RPM", 63.27))
print(string.format("[%5d] [%-5d] [%05d]", 42, 42, 42))
print(string.format("%+d / %+d", 5, -5))
print(string.format("%x %X 100%%", 255, 3054))
print(("%.3s"):format("Andesite"))

1250 items in 20 chests
Speed: 63.3 RPM
[   42] [42   ] [00042]
+5 / -5
ff BEE 100%
And

Columns. A width per column, - for the texts so they line up on the left, nothing for the numbers so they line up on the right:

local stock = {
  {name = "Iron Ingot", count = 1250},
  {name = "Copper Ingot", count = 87},
  {name = "Zinc Nugget", count = 4},
  {name = "Brass Ingot", count = 320},
}
print(string.format("%-14s %6s", "Item", "Count"))
print(string.rep("-", 21))
for _, row in ipairs(stock) do
  print(string.format("%-14s %6d", row.name, row.count))
end

Item            Count
---------------------
Iron Ingot       1250
Copper Ingot       87
Zinc Nugget         4
Brass Ingot       320

A clock. os.day_time() counts the ticks of the Minecraft day, 0 being 6:00 in the morning. %02d writes two digits, with a leading zero:

local function clock(ticks)
  local t = (ticks + 6000) % 24000
  local h = math.floor(t / 1000)
  local m = math.floor(t % 1000 * 60 / 1000)
  return string.format("%02d:%02d", h, m)
end
print(clock(os.day_time()))
print(clock(0), clock(6500), clock(18000))
local seconds = 754
print(string.format("%d:%02d left", seconds // 60, seconds % 60))

12:00
06:00   12:30   00:00
12:34 left

When it fails. string.format is strict, and the program stops:

Extra values are ignored. With %f, infinity and "not a number" are written Infinity and NaN (%s writes inf and nan), and with %x a negative number comes out as 16 hexadecimal digits (-1 gives ffffffffffffffff).

See also tostring() string.rep()

Cuts the text into a list of pieces, at each separator.

A Brass extension that replaces Lua's patterns in most jobs. The separator can be several characters long (", "). The pieces keep everything between two separators, so:

• two separators in a row give an empty piece, and a separator at the start or the end gives an empty piece there;
• a text without the separator gives a list with the whole text, and an empty text gives {""};
• an empty separator "" cuts between every character.

local parts = ("iron,gold,,copper"):split(",")
print(#parts, parts[3] == "", parts[4])
local letters = ("ABC"):split("")
print(#letters, letters[1], letters[3])
print(#("a b"):split(), #(""):split(","))

4   true    copper
3   A   C
2   1

With table.concat, it replaces one piece of text by another everywhere:

print(table.concat(("iron_ingot"):split("_"), " "))

iron ingot

Reading commands typed by the player. Without a separator, split cuts at every single space, so two spaces in a row give an empty word: trim the line and skip the empty words.

local function words(line)
  local out = {}
  for _, w in ipairs(line:trim():split(" ")) do
    if w ~= "" then
      table.insert(out, w)
    end
  end
  return out
end

local function run(line)
  local w = words(line)
  local command = w[1]
  if command == nil then
    return
  end
  if command == "speed" then
    local rpm = tonumber(w[2])
    if rpm == nil then
      print("usage: speed <rpm>")
    else
      print("speed set to " .. rpm .. " RPM")
    end
  elseif command == "open" or command == "close" then
    print(command .. " gate " .. (w[2] or "1"))
  else
    print("unknown command: " .. command)
  end
end

run("speed   128")
run("  open 3 ")
run("speed fast")
run("")
run("jump")

speed set to 128 RPM
open gate 3
usage: speed <rpm>
unknown command: jump

In a real program the lines come from the keyboard: while true do write("> ") run(read()) end.

See also string.trim() table.concat()

Removes the spaces, tabs and line breaks at both ends of the text.

The spaces inside stay. Trim what a player typed and the lines of a file (a file written on another system may end its lines with an invisible \r).

local typed = "   Iron Ingot  \n"
print("[" .. typed:trim() .. "]")

[Iron Ingot]

See also string.split()

The code of one character of the text (the first by default).

Lua can return several codes at once. Brass returns one: call it once per position.

print(string.byte("A"), ("abc"):byte(2), ("abc"):byte(-1))
print(("abc"):byte(10))

65  98  99
nil

Shelves of a storage wall named A1, B4, C12: the letter gives the column.

local function cell(code)
  local column = code:upper():byte(1) - string.byte("A") + 1
  local row = tonumber(code:sub(2))
  return {column = column, row = row}
end
local c = cell("c12")
print(c.column, c.row)

3   12

See also string.char()

Text made of character codes.

string.char() with no code gives "". A code outside 0 to 65535 stops with bad argument #1 to 'char' (value out of range), a code with decimals with bad argument #1 to 'char' (number has no integer representation) (the number is the position of the bad code). Codes below 32 are control characters: the screen shows them as ?.

print(string.char(72, 105))
for i = 1, 5 do
  write(string.char(64 + i) .. " ")
end
print()
print(string.char(("A"):byte() + 1))

Hi
A B C D E
B

See also string.byte()