mirror of
https://github.com/roc-lang/roc.git
synced 2024-11-10 10:02:38 +03:00
146 lines
9.6 KiB
HTML
146 lines
9.6 KiB
HTML
<!doctype html>
|
|
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="utf-8">
|
|
|
|
<title>The Roc Programming Language</title>
|
|
<meta name="description" content="A language for building fast, reliable software.">
|
|
<meta name="viewport" content="width=device-width">
|
|
|
|
<link rel="icon" href="favicon.svg">
|
|
<link rel="stylesheet" href="styles.css">
|
|
</head>
|
|
|
|
<body>
|
|
<div class="container">
|
|
<div class="content">
|
|
<nav class="sidebar">
|
|
<h2 id="sidebar-heading">modules</h2>
|
|
<input id="module-search" aria-labelledby="sidebar-heading" type="text" placeholder="Search" tabindex=0 />
|
|
<a class="sidebar-link" href="#Bool">Bool</a>
|
|
<a class="sidebar-link" href="#Num">Num</a>
|
|
<a class="sidebar-link" href="#Str">Str</a>
|
|
<a class="sidebar-link" href="#List">List</a>
|
|
<a class="sidebar-link" href="#Set">Set</a>
|
|
<a class="sidebar-link" href="#Map">Map</a>
|
|
<a class="sidebar-link" href="#Result">Result</a>
|
|
</nav>
|
|
<div class="main-container">
|
|
<header class="top-header">
|
|
<nav class="main-nav">
|
|
<div class="pkg-and-logo">
|
|
<a class="logo" href="/" aria-labelledby="logo-link">
|
|
<svg viewBox="0 -6 51 58" fill="none" xmlns="http://www.w3.org/2000/svg" aria-labelledby="logo-link" role="img">
|
|
<title id="logo-link">Return to Roc packages</title>
|
|
<defs>
|
|
<linearGradient id="logo-gradient" x2="0.35" y2="1">
|
|
<stop offset="0%" stop-color="var(--logo-gradient-start)" />
|
|
<stop offset="50%" stop-color="var(--logo-gradient-mid)" />
|
|
<stop offset="85%" stop-color="var(--logo-gradient-end)" />
|
|
</linearGradient>
|
|
</defs>
|
|
<polygon role="presentation" points="0,0 23.8834,3.21052 37.2438,19.0101 45.9665,16.6324 50.5,22 45,22 44.0315,26.3689 26.4673,39.3424 27.4527,45.2132 17.655,53 23.6751,22.7086" class="logo-solid"/>
|
|
</svg>
|
|
</a>
|
|
<h1 class="pkg-full-name">
|
|
<a href="/roc/builtins">roc/builtins</a>
|
|
</h1>
|
|
<a class="version" href="/roc/builtins/1.0.0">1.0.0</a>
|
|
</div>
|
|
<label class="search-button" for="module-search">
|
|
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 480 480" width="18" height="18" aria-labelledby="magnifying-glass">
|
|
<title id="magnifying-glass">Search modules</title>
|
|
<path role="presentation" fill="none" stroke="var(--faded-color)" stroke-width="48" stroke-linecap="round" d="m280,278a153,153 0 1,0-2,2l170,170m-91-117 110,110-26,26-110-110"/>
|
|
</svg>
|
|
</label>
|
|
</nav>
|
|
</header>
|
|
<main>
|
|
<h2 class="module-name"><a href="#">Str</a></h2>
|
|
<p>Dealing with text is a deep topic, so by design, Roc's <code><a href="#">Str</a></code> module sticks
|
|
to the basics.
|
|
</p>
|
|
<p><i>For more advanced use cases like working with raw <a href="https://unicode.org/glossary/#code_point">code points</a>,
|
|
see the <a href="roc/unicode">roc/unicode</a> package. For locale-specific text
|
|
functions (including capitalizing a string, as capitalization rules vary by locale)
|
|
see the <a href="roc/locale">roc/locale</a> package.</i></p>
|
|
<h3 id="unicode">Unicode</h3>
|
|
<p>Unicode can represent text values which span multiple languages, symbols, and emoji.
|
|
Here are some valid Roc strings:</p>
|
|
<pre><code>"Roc"
|
|
"鹏"
|
|
"🐼"</code></pre>
|
|
<p>Every Unicode string is a sequence of <a href="https://unicode.org/glossary/#grapheme_cluster">grapheme clusters</a>.
|
|
A grapheme cluster corresponds to what a person reading a string might call a "character",
|
|
but because the term "character" is used to mean many different concepts across
|
|
different programming languages, the documentation for Roc strings intentionally
|
|
avoids it. Instead, we use the term "clusters" as a shorthand for "grapheme clusters."</p>
|
|
<p>You can get the number of grapheme clusters in a string by calling <code><a href="#Str.countClusters">Str.countClusters</a></code> on it:</p>
|
|
<pre><code>Str.countClusters "Roc!" # 4
|
|
Str.countClusters "折り紙" # 3
|
|
Str.countClusters "🐼" # 1</code></pre>
|
|
<p>The <code>countClusters</code> function walks through the entire string to get its answer,
|
|
so if you want to check whether a string is empty, you'll get much better performance
|
|
by calling <code>Str.isEmpty myStr</code> instead of <code>Str.countClusters myStr == 0</code>.</p>
|
|
<h3 id="escape-sequences">Escape sequences</h3>
|
|
<p>If you put a <code>\</code> in a Roc string literal, it begins an <em>escape sequence</em>.
|
|
An escape sequence is a convenient way to insert certain strings into other strings.
|
|
For example, suppose you write this Roc string:</p>
|
|
<pre><code>"It wasn't a rock\nIt was a rock lobster!"</code></pre>
|
|
<p>The <code>"\n"</code> in the middle will insert a line break into this string. There are
|
|
other ways of getting a line break in there, but <code>"\n"</code> is the most common.</p>
|
|
<p>Another way you could insert a newline is by writing <code>\u{0x0A}</code> instead of <code>\n</code>.
|
|
That would result in the same string, because the <code>\u</code> escape sequence inserts
|
|
<a href="https://unicode.org/glossary/#code_point">Unicode code points</a> directly into
|
|
the string. The Unicode code point 10 is a newline, and 10 is <code>0A</code> in hexadecimal.
|
|
<code>0x0A</code> is a Roc hexadecimal literal, and <code>\u</code> escape sequences are always
|
|
followed by a hexadecimal literal inside <code>{</code> and <code>}</code> like this.</p>
|
|
<p>As another example, <code>"R\u{0x6F}c"</code> is the same string as <code>"Roc"</code>, because
|
|
<code>"\u{0x6F}"</code> corresponds to the Unicode code point for lowercase <code>o</code>. If you
|
|
want to <a href="https://en.wikipedia.org/wiki/Metal_umlaut">spice things up a bit</a>,
|
|
you can write <code>"R\u{0xF6}c"</code> as an alternative way to get the string <code>"Röc"</code>.</p>
|
|
<p>Roc strings also support these escape sequences:</p>
|
|
<ul>
|
|
<li><code>\\</code> - an actual backslash (writing a single <code>\</code> always begins an escape sequence!)</li>
|
|
<li><code>\"</code> - an actual quotation mark (writing a <code>"</code> without a <code>\</code> ends the string)</li>
|
|
<li><code>\r</code> - <a href="https://en.wikipedia.org/wiki/Carriage_Return">carriage return</a></li>
|
|
<li><code>\t</code> - <a href="https://en.wikipedia.org/wiki/Tab_key#Tab_characters">horizontal tab</a></li>
|
|
<li><code>\v</code> - <a href="https://en.wikipedia.org/wiki/Tab_key#Tab_characters">vertical tab</a></li>
|
|
</ul>
|
|
<p>You can also use escape sequences to insert named strings into other strings, like so:</p>
|
|
<pre><code>name = "Lee"
|
|
city = "Roctown"
|
|
|
|
greeting = "Hello, \(name)! Welcome to \(city)."</code></pre>
|
|
|
|
<p>Here, <code>greeting</code> will become the string <code>"Hello, Lee! Welcome to Roctown."</code>.
|
|
This is known as <a href="https://en.wikipedia.org/wiki/String_interpolation">string interpolation</a>,
|
|
and you can use it as many times as you like inside a string. The name
|
|
between the parentheses must refer to a <code>Str</code> value that is currently in
|
|
scope, and it must be a name - it can't be an arbitrary expression like a function call.</p>
|
|
<h3 id="encoding">Encoding</h3>
|
|
<p>Roc strings are not coupled to any particular
|
|
<a href="https://en.wikipedia.org/wiki/Character_encoding">encoding</a>. As it happens,
|
|
they are currently encoded in UTF-8, but this module is intentionally designed
|
|
not to rely on that implementation detail so that a future release of Roc can
|
|
potentially change it without breaking existing Roc applications. (UTF-8
|
|
seems pretty great today, but so did UTF-16 at an earlier point in history.)</p>
|
|
<p>This module has functions to can convert a <code><a href="#Str">Str</a></code> to a <code><a href="#List">List</a></code> of raw <a href="https://unicode.org/glossary/#code_unit">code unit</a>
|
|
integers (not to be confused with the <a href="https://unicode.org/glossary/#code_point">code points</a>
|
|
mentioned earlier) in a particular encoding. If you need encoding-specific functions,
|
|
you should take a look at the <a href="roc/unicode">roc/unicode</a> package.
|
|
It has many more tools than this module does!
|
|
<h3 id="types">Types</h3>
|
|
<code class="code-snippet"><a id="Str.Str" class="type-def" href="#Str.Str">Str</a></code>
|
|
<p>A <a href="https://unicode.org">Unicode</a> text value.</p>
|
|
</main>
|
|
</div>
|
|
</div>
|
|
<footer>
|
|
<p>Made by people who like to make nice things.</p>
|
|
<p>© 2020-present</p></footer>
|
|
</div>
|
|
</body>
|
|
</html>
|