Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Output, Math and Logic

These builtins print to the console, build text, do arithmetic and pause the program. They need no window, so every example on this page runs in a plain terminal with ling run.

All numbers in Ling are 64-bit floating point. Whole values print without a decimal point (3, not 3.0). Angles are in radians. A missing trailing numeric argument usually takes a default instead of raising an error.

Summary

Output and results

Builtin中文日本語한국어ไทยPurpose
print(value, ...)印, 打印印刷출력พิมพ์Print the arguments, joined with no separator, then a newline
println(value, ...)印, 打印印刷출력พิมพ์Same builtin as print
print_file(text)———พิมพ์ไฟล์Print text without a newline
print_color(color, value, ...)———พิมพ์สีPrint a line in a bright ANSI colour
format(template, value, ...)格式フォーマット서식รูปแบบFill {} placeholders in a template
format::join(list)格式::拼接———Concatenate list items as text
ok(value)好良し좋아โอเคWrap a success result
bad(reason)坏悪い나쁨ผิดWrap a failure result (alias err)
try(function, arg, ...)————Call a function, turning a runtime error into bad
sleep(ms)睡眠眠る, スリープ잠자기, 잠นอนPause for a number of milliseconds

Math

Builtin中文日本語한국어ไทยPurpose
abs(x)绝对值, 绝对絶対値절댓값, 절대값ค่าสัมบูรณ์Absolute value
floor(x)向下取整, 下整床関数내림ปัดลงRound down
ceil(x)向上取整, 上整天井関数올림ปัดขึ้นRound up
round(x)四舍五入, 四舍四捨五入반올림ปัดเศษRound to nearest; halves go away from zero
trunc(x)取整, 截整整数化, 切り捨て정수화, 버림ตัดทศนิยมDrop the fraction (alias int)
fract(x)小数部分—소수부—Fractional part
min(a, b)最小最小최솟값ต่ำสุดSmaller of two numbers
max(a, b)最大最大최댓값สูงสุดLarger of two numbers
clamp(x, low, high)截取範囲制限범위제한จำกัดLimit x to low..high
sign(x)符号符号関数부호เครื่องหมาย-1 for negative, otherwise 1
sqrt(x)根平方根제곱근รากที่สองSquare root
cbrt(x)立方根—세제곱근รากที่สามCube root
pow(base, exp)幂べき乗거듭제곱ยกกำลังPower
exp(x)指数—지수—e to the power x
ln(x)对数対数로그ลอการิทึมNatural logarithm (alias log)
log2(x), log10(x)对数2, 对数10—로그2, 로그10—Base-2 and base-10 logarithms
hypot(x, y)斜边—빗변—sqrt(x*x + y*y)
sin(x), cos(x), tan(x)正弦, 余弦, 正切サイン, コサイン, タンジェント사인, 코사인, 탄젠트ไซน์, โคไซน์, แทนเจนต์Trigonometry (radians)
asin(x), acos(x), atan(x)反正弦, 反余弦, 反正切アークサイン, アークコサイン, アークタンジェント아크사인, 아크코사인, 아크탄젠트อาร์กไซน์, อาร์กโคไซน์, อาร์กแทนเจนต์Inverse trigonometry
atan2(y, x)反正切2アークタンジェント2아크탄젠트2—Angle of the point (x, y)
tanh(x)双曲正切—쌍곡탄젠트—Hyperbolic tangent
pi()圆周率円周率파이พาย3.14159…
tau()双周率タウ타우ทาว2 × pi
lerp(a, b, t)线性插值線形補間선형보간ค่าระหว่างa + (b - a) * t
smoothstep(low, high, x)平滑步进スムーズステップ스무스스텝เปลี่ยนแบบนุ่มSmooth 0-to-1 S-curve
vnoise(x, y, seed)柏林噪声2Dバリューノイズ2D값노이즈2Dนอยส์2ดีSmooth 2D value noise, 0..1
fbm(x, y, octaves, seed)分形噪声フラクタルノイズ프랙탈노이즈นอยส์ออร์แกนิกLayered (fractal) noise
perlin(x, y, z)柏林噪声3Dパーリンノイズ3D펄린노이즈3Dเพอร์ลิน3ดี3D Perlin noise, about -1..1
rand()随机乱数난수สุ่มRandom number in 0 up to 1

Output

print(value, ...) and println(value, ...)

print and println are the same builtin. Each argument is converted to text, the pieces are joined with no separator, and a newline is added. Lists print as [1, 2, 3], results as Ok(v) and Err(e).

bind start = do {
  print("Hello, Ling!")
  print(42, " ", 3.5, " ", true)
  print([1, 2, 3])
  print("sum", 1 + 2)
  print("sum ", 1 + 2)
}
Hello, Ling!
42 3.5 true
[1, 2, 3]
sum3
sum 3

Put spaces inside the strings yourself, or build the line with format.

Prints its first argument without a newline. Despite the name, it does not touch the file system. It is the only way to keep printing on the same line.

bind start = do {
  for i in 1..4 {
    print_file(i)
    print_file(" ")
  }
  print("go!")
}
1 2 3 go!

Prints a line in a bold, bright ANSI colour. color is 0 to 7: black, red, green, yellow, blue, magenta, cyan, white. The remaining arguments are joined like print. The escape codes are written as-is, so they show up as control characters if you redirect the output to a file.

bind start = do {
  print_color(2, "ok: ", "all tests passed")
  print_color(1, "error!")
}

format(template, value, ...)

Returns text with each {} replaced by the next argument. {:.N} formats a number with N decimal places. A {} with no matching argument becomes empty; extra arguments are ignored. Only {} and {:.N} are supported (no widths, no {0} or {name}, no escaped braces).

bind start = do {
  print(format("{} + {} = {}", 2, 3, 2 + 3))
  print(format("pi is about {:.3}", pi()))
  print(format("{:.1}%", 45.678))
  print(format("{} and {}", "only one"))
}
2 + 3 = 5
pi is about 3.142
45.7%
only one and 

format::join(list) concatenates every item as text with no separator. To put something between the items, use list_join (see Text and Lists).

Results

ok(value) and bad(reason)

Ling has no exceptions. A function that can fail returns ok(value) or bad(reason), and the caller unpacks it with match. They print as Ok(...) and Err(...); err is an English alias of bad. See Errors and Results for the full story.

fn half(n) {
  if n % 2 == 0 { ok(n / 2) } else { bad("odd number") }
}
bind start = do {
  print(half(10))
  print(half(7))
  print(match half(7) { ok(v) => v, bad(e) => "failed: " + e })
}
Ok(5)
Err(odd number)
failed: odd number

try(function, arg, ...)

Calls function with the remaining arguments. Returns ok(result), or bad(message) if the call raised a runtime error.

Interpreter only. The default backend passes functions and closures given as arguments as (), so try returns Err(try: first argument must be a function). Run programs that use try with ling run --interp. A closure with no parameters is written | | expr, with a space.

fn safe_read(path) { try(| | read_file(path)) }

Math

Rounding

floor rounds down, ceil rounds up, round rounds to the nearest whole number (halves go away from zero), trunc drops the fraction, and fract keeps only the fraction. int is an English alias of trunc: it does not convert text to a number (use to_number for that).

bind start = do {
  print(floor(2.7), " ", floor(0 - 2.1))
  print(ceil(2.1), " ", ceil(0 - 2.9))
  print(round(2.5), " ", round(2.4), " ", round(0 - 2.5))
  print(trunc(2.9), " ", trunc(0 - 2.9), " ", int(7.99))
  print(fract(2.25))
}
2 -3
3 -2
3 2 -3
2 -2 7
0.25

min, max, clamp, sign, abs

min and max take exactly two numbers; for a list use list_min and list_max. clamp defaults to the range 0..1 and swaps the bounds if low > high. sign(0) is 1, not 0.

bind start = do {
  print(min(3, 1), " ", max(3, 1))
  print(clamp(15, 0, 10), " ", clamp(0 - 3, 0, 10))
  print(sign(0 - 4), " ", sign(0), " ", abs(0 - 7))
}
1 3
10 0
-1 1 7

Powers, roots and logarithms

sqrt of a negative number is NaN. log is the natural logarithm (same as ln); use log10 for base 10.

bind start = do {
  print(sqrt(16), " ", pow(2, 10), " ", pow(9, 0.5))
  print(cbrt(27), " ", hypot(3, 4), " ", exp(1))
  print(ln(exp(2)), " ", log(1), " ", log2(8), " ", log10(1000))
  print(sqrt(0 - 1))
}
4 1024 3
3 5 2.718281828459045
2 0 3 3
NaN

Trigonometry and constants

Angles are in radians. Always call pi() and tau() with parentheses: a bare pi is () under the default backend.

bind start = do {
  print(sin(pi() / 2), " ", cos(pi()))
  print(atan2(1, 1) * 4)
  print(tau())
}
1 -1
3.141592653589793
6.283185307179586

Interpolation and noise

lerp(a, b, t) does not clamp t. smoothstep(low, high, x) returns 0 below low, 1 above high, and a smooth curve between. The noise functions are deterministic: the same arguments always give the same value, which makes them handy for terrain and textures.

bind start = do {
  print(lerp(0, 10, 0.25), " ", smoothstep(0, 1, 0.5), " ", smoothstep(0, 1, 2))
  print(vnoise(1.5, 2.5, 0) == vnoise(1.5, 2.5, 0))
  print(fbm(0.3, 0.7, 4, 1) >= 0)
}
2.5 0.5 1
true
true

rand()

Returns a pseudo-random number from 0 up to (not including) 1. There is no seed and no integer form, so scale and round it yourself. It is not for security: use random_hex (see Files, Time and System) for unpredictable values.

bind start = do {
  bind die = floor(rand() * 6) + 1
  print(die >= 1 && die <= 6)
}
true

Logic and comparison

Logic and comparison are operators, not builtins: ==, !=, <, <=, >, >=, &&, || and !. Numbers, text and booleans compare by value. Two gotchas: lists are never equal under == (compare their items instead), and ordering text with < is not reliable.

bind start = do {
  print(1 < 2 && !(3 == 4))
  print("a" == "a", " ", 2 != 3)
  print([1, 2] == [1, 2])
}
true
true true
false

Pausing

sleep(ms)

Pauses the program for the given number of milliseconds (sleep_ms is an English alias). To measure time, see time_now in Files, Time and System.

bind start = do {
  sleep(50)
  print("done")
}
done