<!DOCTYPE html>

<html lang="en">

<head>

<meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<!--Old html 4.0.1 way <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> -->

<!--<meta charset="UTF-8">--><!-- New HTML5 way -->

<!-- Mobile -->

<meta name="viewport" content="width=device-width, initial-scale=1"><!-- Favourite icon -->

<link rel="apple-touch-icon" sizes="180x180" href="https://naev.org/favicon-180.png">

<link rel="icon" type="image/png" sizes="196x196" href="https://naev.org/favicon-196.png">

<link rel="icon" type="image/png" sizes="128x128" href="https://naev.org/favicon-128.png">

<link rel="icon" type="image/png" sizes="64x64" href="https://naev.org/favicon-64.png">

<link rel="icon" type="image/png" sizes="32x32" href="https://naev.org/favicon-32.png">

<link rel="icon" type="image/png" sizes="16x16" href="https://naev.org/favicon-16.png">

<link rel="shortcut icon" type="image/x-icon" href="https://naev.org/favicon.ico">

<link rel="stylesheet" href="../ldoc.css"><!-- CSS -->

<link rel="stylesheet" href=https://naev.org/style.css><!-- CSS -->

<!-- EnlighterJS Resources !-->

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/enlighterjs@3.4.0/dist/enlighterjs.min.css" />

<title>Naev Lua API</title><!-- Website information -->

</head>

<body class="bg-light">

<div id="naev-header" class="container-fluid nebula-bg">

<canvas id="nebula-canvas-0"></canvas>

<div class="container" style="position: relative; z-index: 1;">

<a href="https://naev.org/"><img src="https://naev.org/imgs/naev.png" alt="Naev"></a>

</div>

</div>

<nav class="navbar navbar-expand-sm navbar-dark bg-dark">

<div class="container">

<a class="p-0 navbar-brand" href="#"><img id="logo" class="img-fluid" src="https://naev.org/favicon.png" alt=

"Naev"></a> <button class="navbar-toggler" type="button" data-toggle="collapse" data-target=

"#navbarNavAltMarkup" aria-controls="navbarNavAltMarkup" aria-expanded="false" aria-label=

"Toggle navigation"><span class="navbar-toggler-icon"></span></button>

<div class="collapse navbar-collapse justify-content-between" id="navbarNavAltMarkup">

<ul class="navbar-nav">

<li class="nav-item">

<a class="nav-link" href="https://naev.org/">Home</a>

</li>

<li class="nav-item">

<a class="nav-link" href="https://naev.org/page/1/">Blarg</a>

</li>

<li class="nav-item">

<a class="nav-link" href="https://naev.org/media/">Media</a>

</li>

<li class="nav-item">

<a class="nav-link" href="https://naev.org/downloads/">Downloads</a>

</li>

<li class="nav-item">

<a class="nav-link" href="https://naev.org/contact/">Contact</a>

</li>

<li class="nav-item">

<a class="nav-link" href="https://github.com/naev/naev">Github</a>

</li>

<li class="nav-item">

<a class="nav-link" href="https://github.com/naev/naev/wiki">Wiki</a>

</li>

<li class="nav-item">

<a class="nav-link" href="https://naev.org/api/">Lua API</a>

</li>

<li class="nav-item">

<a class="nav-link" href="https://naev.org/devmanual/">Dev Manual</a>

</li>

</ul>

</div>

</div>

</nav>

<div id="lDoc_container">

<div id="main">

<!-- Menu -->

<div id="navigation">

<br/>

<h1>Naev Lua API</h1>

<ul>

<li><a href="../index.html">Index</a></li>

</ul>

<h2>Modules</h2>

<ul class="$(kind=='Topics' and '' or 'nowrap'">

<li><a href="../modules/ai.html">ai</a></li>

<li><a href="../modules/asteroid.html">asteroid</a></li>

<li><a href="../modules/audio.html">audio</a></li>

<li><a href="../modules/bkg.html">bkg</a></li>

<li><a href="../modules/camera.html">camera</a></li>

<li><a href="../modules/canvas.html">canvas</a></li>

<li><a href="../modules/cinema.html">cinema</a></li>

<li><a href="../modules/colour.html">colour</a></li>

<li><a href="../modules/commodity.html">commodity</a></li>

<li><a href="../modules/data.html">data</a></li>

<li><a href="../modules/diff.html">diff</a></li>

<li><a href="../modules/equipopt.optimize.html">equipopt.optimize</a></li>

<li><a href="../modules/escort.html">escort</a></li>

<li><a href="../modules/evt.html">evt</a></li>

<li><a href="../modules/faction.html">faction</a></li>

<li><a href="../modules/file.html">file</a></li>

<li><a href="../modules/fleet.html">fleet</a></li>

<li><a href="../modules/font.html">font</a></li>

<li><strong>format</strong></li>

<li><a href="../modules/gfx.html">gfx</a></li>

<li><a href="../modules/gui.html">gui</a></li>

<li><a href="../modules/hook.html">hook</a></li>

<li><a href="../modules/jump.html">jump</a></li>

<li><a href="../modules/lazyload.html">lazyload</a></li>

<li><a href="../modules/linenoise.html">linenoise</a></li>

<li><a href="../modules/linopt.html">linopt</a></li>

<li><a href="../modules/lmisn.html">lmisn</a></li>

<li><a href="../modules/lmusic.html">lmusic</a></li>

<li><a href="../modules/love_shaders.html">love_shaders</a></li>

<li><a href="../modules/luatk.html">luatk</a></li>

<li><a href="../modules/misn.html">misn</a></li>

<li><a href="../modules/munition.html">munition</a></li>

<li><a href="../modules/music.html">music</a></li>

<li><a href="../modules/naev.html">naev</a></li>

<li><a href="../modules/news.html">news</a></li>

<li><a href="../modules/outfit.html">outfit</a></li>

<li><a href="../modules/pilot.html">pilot</a></li>

<li><a href="../modules/pilotai.html">pilotai</a></li>

<li><a href="../modules/pilotoutfit.html">pilotoutfit</a></li>

<li><a href="../modules/player.html">player</a></li>

<li><a href="../modules/portrait.html">portrait</a></li>

<li><a href="../modules/pp_shaders.html">pp_shaders</a></li>

<li><a href="../modules/prng.html">prng</a></li>

<li><a href="../modules/prob.html">prob</a></li>

<li><a href="../modules/proximity.html">proximity</a></li>

<li><a href="../modules/rnd.html">rnd</a></li>

<li><a href="../modules/safelanes.html">safelanes</a></li>

<li><a href="../modules/shader.html">shader</a></li>

<li><a href="../modules/ship.html">ship</a></li>

<li><a href="../modules/shiplog.html">shiplog</a></li>

<li><a href="../modules/spfx.html">spfx</a></li>

<li><a href="../modules/spob.html">spob</a></li>

<li><a href="../modules/swapship.html">swapship</a></li>

<li><a href="../modules/system.html">system</a></li>

<li><a href="../modules/tex.html">tex</a></li>

<li><a href="../modules/time.html">time</a></li>

<li><a href="../modules/tk.html">tk</a></li>

<li><a href="../modules/transform.html">transform</a></li>

<li><a href="../modules/var.html">var</a></li>

<li><a href="../modules/vn.html">vn</a></li>

<li><a href="../modules/vntk.html">vntk</a></li>

</ul>

</div>

<div id="content">

<h1>Module <code>format</code></h1>

<p>Provides string formatting and interpolation facilities.</p>

<p> The benefits of using it are easy internationalization and consistency with the rest of Naev.

The number formatters handle plural forms in the user's language, digit separators, and abbreviations.

String interpolation (format.f) allows for named parameters ("Fly to {planet} in the {system} system"),

whereas string.format is positional ("Fly to %s in the %s system") and locks translators into the English word order.</p>

<h2><a href="#Functions">Functions</a></h2>

<table class="function_list">

<tr>

<td class="name" nowrap><a href="#credits">credits (credits)</a></td>

<td class="summary">Converts a number of credits to a string.</td>

</tr>

<tr>

<td class="name" nowrap><a href="#f">f (str, tab)</a></td>

<td class="summary">String interpolation, inspired by <a href="https://github.com/hishamhm/f-strings">f-strings</a> but closer to Python's str.format().</td>

</tr>

<tr>

<td class="name" nowrap><a href="#humanize">humanize (num)</a></td>

<td class="summary">Converts a number to a human readable string.</td>

</tr>

<tr>

<td class="name" nowrap><a href="#jumps">jumps (jumps)</a></td>

<td class="summary">Converts a number of jumps to a string, utilizing ngettext.</td>

</tr>

<tr>

<td class="name" nowrap><a href="#list">list (words)</a></td>

<td class="summary">A version of string.gsub returning just the string.</td>

</tr>

<tr>

<td class="name" nowrap><a href="#number">number (number)</a></td>

<td class="summary">Converts a nonnegative integer into a human readable string, delimiting every third digit with a comma.</td>

</tr>

<tr>

<td class="name" nowrap><a href="#reward">reward (reward_list)</a></td>

<td class="summary">Converts an item object or number of credits to reward string ("You have received _").</td>

</tr>

<tr>

<td class="name" nowrap><a href="#tonnes">tonnes (tonnes)</a></td>

<td class="summary">Converts a number of tonnes to a string, using ngettext.</td>

</tr>

<tr>

<td class="name" nowrap><a href="#tonnes_short">tonnes_short (tonnes)</a></td>

<td class="summary">Like fmt.tonnes, but for abbreviations.</td>

</tr>

</table>

<br/>

<br/>

<h2><a name="Functions"></a>Functions</h2>

<dl class="function">

<dt>

<a name = "credits"></a>

<strong>credits (credits)</strong>

</dt>

<dd>

Converts a number of credits to a string. </p>

<p> Should be used everywhere a number of credits is displayed.

<h3>Parameters:</h3>

<ul>

<li><span class="parameter">credits</span>

Number of credits.

</li>

</ul>

<h3>Returns:</h3>

<ol>

A string taking the form of "X ¤".

</ol>

<h3>Usage:</h3>

<ul>

<pre data-enlighter-language="lua" class="example">vn.na(fmt.f(_(&quot;You have been paid {credits}.&quot;), {credits=fmt.credits(credits)}))

</pre>

</ul>

</dd>

<dt>

<a name = "f"></a>

<strong>f (str, tab)</strong>

</dt>

<dd>

String interpolation, inspired by <a href="https://github.com/hishamhm/f-strings">f-strings</a> but closer to Python's str.format(). </p>

<p> Prefer this over string.format because it allows translations to change the word order.

It also lets you use objects in the formatting (if they support tostring()), whereas string.format can only do this under LuaJIT.

<h3>Parameters:</h3>

<ul>

<li><span class="parameter">str</span>

<span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>

<p> Format string which may include placeholders of the form "{var}" "{var:6.3f}"</p>

<pre><code> (where the expression after the colon is any directive string.format understands).

</code></pre>

</li>

<li><span class="parameter">tab</span>

<span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.6">table</a></span>

Argument table.

</li>

</ul>

<h3>Usage:</h3>

<ul>

<li><pre data-enlighter-language="lua" class="example">fmt.f(_(&quot;Deliver the loot to {pnt} in the {sys} system&quot;),{pnt=returnpnt, sys=returnsys})

</pre></li>

<li><pre data-enlighter-language="lua" class="example">fmt.f(_(&quot;As easy as {1}, {2}, {3}&quot;), {&quot;one&quot;, &quot;two&quot;, &quot;three&quot;})

</pre></li>

<li><pre data-enlighter-language="lua" class="example">fmt.f(_(&quot;A few digits of pi: {1:.2f}&quot;), {math.pi})

</pre></li>

</ul>

</dd>

<dt>

<a name = "humanize"></a>

<strong>humanize (num)</strong>

</dt>

<dd>

Converts a number to a human readable string. </p>

<p>Has to be implemented on a per-language basis.

<h3>Parameters:</h3>

<ul>

<li><span class="parameter">num</span>

<span class="types"><a class="type" href="../modules/format.html#number">number</a></span>

Number to convert to a human readable string.

</li>

</ul>

<h3>Returns:</h3>

<ol>

<span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>

Human readable string.

</ol>

</dd>

<dt>

<a name = "jumps"></a>

<strong>jumps (jumps)</strong>

</dt>

<dd>

Converts a number of jumps to a string, utilizing ngettext. </p>

<p> This adds "jumps" to the output of fmt.number in a translatable way.

Caution: Usage within sentences can backfire, if the correct grammar to use

depends on the number of jumps. Using ngettext (n_) on full sentences is

safer where practical.

<h3>Parameters:</h3>

<ul>

<li><span class="parameter">jumps</span>

Number of jumps.

</li>

</ul>

<h3>Returns:</h3>

<ol>

A string taking the form of "X jump" or "X jumps".

</ol>

<h3>Usage:</h3>

<ul>

<pre data-enlighter-language="lua" class="example">vn.na(fmt.f(_(&quot;The system is {jumps} away.&quot;), {jumps=fmt.jumps(jumps)}))

</pre>

</ul>

</dd>

<dt>

<a name = "list"></a>

<strong>list (words)</strong>

</dt>

<dd>

A version of string.gsub returning just the string. --]]local function _replace(template, index, text)

local str = string.gsub(template, index, tostring(text))

return str

end</p>

<p>--[[--

Creates a translatable list of words.</p>

<p> Taken from <a href="https://stackoverflow.com/questions/43081112/localization-of-lists/58033018#58033018">this post</a>.

<h3>Parameters:</h3>

<ul>

<li><span class="parameter">words</span>

<span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.6">table</a></span>

List of words to translate such as {"one","two","three"}.

</li>

</ul>

<h3>Returns:</h3>

<ol>

<span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>

String of the list of words such as "one, two, and three"

</ol>

</dd>

<dt>

<a name = "number"></a>

<strong>number (number)</strong>

</dt>

<dd>

Converts a nonnegative integer into a human readable string, delimiting every third digit with a comma.

If you pass a more exotic "number" value, you'll get a string back, but you won't attain happiness.

<h3>Parameters:</h3>

<ul>

<li><span class="parameter">number</span>

The number to format. Will be rounded to the nearest integer.

</li>

</ul>

</dd>

<dt>

<a name = "reward"></a>

<strong>reward (reward_list)</strong>

</dt>

<dd>

Converts an item object or number of credits to reward string ("You have received _").

<h3>Parameters:</h3>

<ul>

<li><span class="parameter">reward_list</span>

<p> Thing or number of credits the player is receiving.</p>

<pre><code> Avoid passing strings (English or translated) for clarity's sake. Can be a table containing multiple instances.

</code></pre>

</li>

</ul>

<h3>Returns:</h3>

<ol>

A string taking the form of "You have received X." -- translated and colourized.

</ol>

<h3>Usage:</h3>

<ul>

<pre data-enlighter-language="lua" class="example">vn.na(fmt.reward(money_reward))

</pre>

</ul>

</dd>

<dt>

<a name = "tonnes"></a>

<strong>tonnes (tonnes)</strong>

</dt>

<dd>

Converts a number of tonnes to a string, using ngettext. </p>

<p> This adds "tonnes" to the output of fmt.number in a translatable way.

Caution: Usage within sentences can backfire, if the correct grammar to use

depends on the number of tonnes. Using ngettext (n_) on full sentences is

safer where practical.

<h3>Parameters:</h3>

<ul>

<li><span class="parameter">tonnes</span>

Number of tonnes.

</li>

</ul>

<h3>Returns:</h3>

<ol>

A string taking the form of "X tonne" or "X tonnes".

</ol>

<h3>Usage:</h3>

<ul>

<pre data-enlighter-language="lua" class="example">vn.na(fmt.f(_(&quot;You are carrying {tonnes}&quot;), {tonnes=fmt.tonnes(tonnes)}))

</pre>

</ul>

</dd>

<dt>

<a name = "tonnes_short"></a>

<strong>tonnes_short (tonnes)</strong>

</dt>

<dd>

Like fmt.tonnes, but for abbreviations.

<h3>Parameters:</h3>

<ul>

<li><span class="parameter">tonnes</span>

Number of tonnes.

</li>

</ul>

<h3>Returns:</h3>

<ol>

A short string like "22 t" describing the given mass.

</ol>

</dd>

</dl>

</div> <!-- id="content" -->

</div> <!-- id="main" -->

<div id="about">

<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.5.0</a></i>

<i style="float:right;">Last updated 2025-08-31 00:15:12 </i>

</div> <!-- id="about" -->

</div> <!-- id="container" -->

<div id="naev-footer" class="container-fluid nebula-bg mt-5">

<canvas id="nebula-canvas-1"></canvas>

<div class="container" style="position: relative; z-index: 1;">

<footer class="row text-muted">

<p class="col-xs-12 col-sm-6 text-left">© 2025 Naev Development Blarg</p>

<p class="col-xs-12 col-sm-6 text-right">Original content licensed under <a href=

"https://creativecommons.org/licenses/by-sa/4.0/">CC-by-sa 4.0</a></p>

</footer>

</div>

</div>

<!-- Naev.org Javascript -->

<script type="text/javascript" src="https://naev.org/site.js"></script>

<!-- EnlighterJS -->

<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/enlighterjs@3.4.0/dist/enlighterjs.min.js">

integrity="sha384-qMvs9nZ6afccojk2J2vg2CwyiHc5m/k1nb9VWa+otyt3VK4agPEc9/pfWC/iOxkG"

crossorigin="anonymous">

</script>

<!-- Init Code -->

<script type="text/javascript">

// - highlight all pre + code tags (CSS3 selectors)

// - use theme "enlighter"

// - replace tabs with 2 spaces

EnlighterJS.init('pre', 'code', {

language : 'lua',

theme: 'enlighter',

indent : 2

});

</script>

</body>

</html>