<commit_before>\section{String}

A \dfn{string} is a sequence of characters.

\subsection{Prototypes}
\begin{itemize}
\item \refObject{Comparable}
\item \refObject{Orderable}
\end{itemize}

\subsection{Construction}
The simplest way to create fresh String is by using the literal
syntax. A null String can also be obtained with \lstinline|String|'s
\lstinline|new| method.

\begin{urbiscript}
String.new;
[00000000] ""
String;
[00000000] ""
"123";
[00000000] "123"
\end{urbiscript}

\subsection{Methods}
\begin{itemize}
\item \lstinline|asFloat|\\
  If the whole content of \lstinline|this| is an integer, return its
  value, otherwise return an error.
\begin{urbiscript}[firstnumber=last]
"23.03".asFloat;
[00000000] 23.03

"123abc".asFloat;
[00000001:error] !!! asFloat: unable to convert to float: "123abc"
\end{urbiscript}

\item \lstinline|asList|\\
  Return a List of one-letter Strings that, concataneted, equal
  \lstinline|this|.  This allows to use \lstinline|for| to iterate
  over the string.
\begin{urbiscript}[firstnumber=last]
assert("123".asList == ["1", "2", "3"]);
for (var v : "123")
  echo(v);
[00000001] *** 1
[00000001] *** 2
[00000001] *** 3
\end{urbiscript}

\item \lstinline|asPrintable|\\
  Return \lstinline|this| as a literal (escaped) string.
\begin{urbiscript}[firstnumber=last]
assert("foo".asPrintable == "\"foo\"");
assert("foo".asPrintable.asPrintable == "\"\\\"foo\\\"\"");
\end{urbiscript}

\item \lstinline|asString|\\
  Return \lstinline|this|.
\begin{urbiscript}[firstnumber=last]
assert("\"foo\"".asString == "\"foo\"");
\end{urbiscript}

\item \lstinline|distance(\var{other})|\\
  Return the
  \href{http://en.wikipedia.org/wiki/Damerau-Levenshtein_distance}
  {Damerau-Levenshtein distance} between \lstinline|this| and
  \var{other}.  The more alike the strings are, the smaller the
  distance is.
\begin{urbiscript}[firstnumber=last]
assert("foo".distance("foo") == 0);
assert("bar".distance("baz") == 1);
assert("foo".distance("bar") == 3);
\end{urbiscript}

\item \lstinline|fresh|\\
  Return a String that has never been used as an identifier, prefixed
  by \lstinline|this|.  It can safely be used with
  \lstinline|Object.setSlot| and so forth.
\begin{urbiscript}[firstnumber=last]
assert(String.fresh == "_5");
assert("foo".fresh == "foo_6");
\end{urbiscript}

\item \lstinline|replace(\var{from}, \var{to})|\\
  Replace every occurrence of the string \var{from} in
  \lstinline|this| by \var{to}, and return the result.
  \lstinline|this| is not modified.
\begin{urbiscript}[firstnumber=last]
assert("Hello == World!".replace("Hello", "Bonjour")
                      .replace("World!", "Monde !"),
       "Bonjour, Monde !");
\end{urbiscript}

\item \lstinline|size|\\
  Return the size of the string.
\begin{urbiscript}[firstnumber=last]
assert("foo".size == 3);
assert("".size == 0);
\end{urbiscript}

\item \lstinline|toLower|\\
  Make lower case every upper case character in \lstinline|this| and
  return the result.  \lstinline|this| is not modified.
\begin{urbiscript}[firstnumber=last]
assert("Hello == World!".toLower, "hello, world!");
\end{urbiscript}

\item \lstinline|toUpper|\\
  Make upper case every lower case character in \lstinline|this| and
  return the result.  \lstinline|this| is not modified.
\begin{urbiscript}[firstnumber=last]
assert("Hello == World!".toUpper, "HELLO, WORLD!");
\end{urbiscript}

\item \lstinline|'%'(\var{args})|\\
  Use \lstinline|this| as format string, and convert occurrences of
  \lstinline|%s| in \lstinline|this| by the \var{args} converted as
  strings via \lstinline|asString|.
%  This construct is actually more
%  powerful than this, since it relies on
%  \href{http://www.boost.org/doc/libs/1_39_0/libs/format/doc/format.html,
%    Boost.Format}.  For instance:
\begin{urbiscript}[firstnumber=last]
assert("%s + %s = %s" % [1 == 2, 3], "1 + 2 = 3");
\end{urbiscript}

\item \lstinline|'*'(\var{n})|\\
  Return the concatentation of \lstinline|this| \var{n} times.
\begin{urbiscript}[firstnumber=last]
assert("foo" * 0 == "");
assert("foo" * 1 == "foo");
assert("foo" * 3 == "foofoofoo");
\end{urbiscript}

\item \lstinline|'+'(\var{other})|\\
  Return the concatenation of \lstinline|this| and
  \lstinline|\var{other}.asString|.
\begin{urbiscript}[firstnumber=last]
assert("foo" + "bar" == "foobar");
assert("foo" + "" == "foo");
assert("foo" + 3 == "foo3");
assert("foo" + [1 == 2, 3], "foo[1, 2, 3]");
\end{urbiscript}

\item \lstinline|'<'(\var{other})|\\
  Whether \lstinline|this| is lexicographically before \var{other},
  which must be a String.
\begin{urbiscript}[firstnumber=last]
assert("" < "a");
assert(!("a" < ""));
assert("a" < "b");
assert(!("a" < "a"));
\end{urbiscript}

\item \lstinline|'[]'(\var{from})|\\
  \lstinline|'[]'(\var{from}, \var{to})|\\
  Return the substring starting at \var{from}, up to and not including
  \var{to} (which defaults to \var{to} + 1).
\begin{urbiscript}[firstnumber=last]
assert("foobar"[0 == 3], "foo");
assert("foobar"[0] == "f");
\end{urbiscript}

\item \lstinline|'[]='(\var{from}, \var{other})|\\
  \lstinline|'[]='(\var{from}, \var{to}, \var{other})|\\
  Replace the substring starting at \var{from}, up to and not including
  \var{to} (which defaults to \var{to} + 1), by \var{other}.  Return
  \var{other}.

  Beware that this routine is imperative: it changes the value of
  \lstinline|this|.
\begin{urbiscript}[firstnumber=last]
var s1 = "foobar" | var s2 = s1 |
assert(s1[0 == 3] = "quux", "quux");
assert(s1 == "quuxbar");
assert(s2 == "quuxbar");
assert(s1[4 == 7] = "", "");
assert(s2 == "quux");
\end{urbiscript}
\end{itemize}

%%% Local Variables:
%%% mode: latex
%%% TeX-master: "../urbi-sdk"
%%% End:
<commit_msg>doc: fix assertion.<commit_after>\section{String}

A \dfn{string} is a sequence of characters.

\subsection{Prototypes}
\begin{itemize}
\item \refObject{Comparable}
\item \refObject{Orderable}
\end{itemize}

\subsection{Construction}
The simplest way to create fresh String is by using the literal
syntax. A null String can also be obtained with \lstinline|String|'s
\lstinline|new| method.

\begin{urbiscript}
String.new;
[00000000] ""
String;
[00000000] ""
"123";
[00000000] "123"
\end{urbiscript}

\subsection{Methods}
\begin{itemize}
\item \lstinline|asFloat|\\
  If the whole content of \lstinline|this| is an integer, return its
  value, otherwise return an error.
\begin{urbiscript}[firstnumber=last]
"23.03".asFloat;
[00000000] 23.03

"123abc".asFloat;
[00000001:error] !!! asFloat: unable to convert to float: "123abc"
\end{urbiscript}

\item \lstinline|asList|\\
  Return a List of one-letter Strings that, concataneted, equal
  \lstinline|this|.  This allows to use \lstinline|for| to iterate
  over the string.
\begin{urbiscript}[firstnumber=last]
assert("123".asList == ["1", "2", "3"]);
for (var v : "123")
  echo(v);
[00000001] *** 1
[00000001] *** 2
[00000001] *** 3
\end{urbiscript}

\item \lstinline|asPrintable|\\
  Return \lstinline|this| as a literal (escaped) string.
\begin{urbiscript}[firstnumber=last]
assert("foo".asPrintable == "\"foo\"");
assert("foo".asPrintable.asPrintable == "\"\\\"foo\\\"\"");
\end{urbiscript}

\item \lstinline|asString|\\
  Return \lstinline|this|.
\begin{urbiscript}[firstnumber=last]
assert("\"foo\"".asString == "\"foo\"");
\end{urbiscript}

\item \lstinline|distance(\var{other})|\\
  Return the
  \href{http://en.wikipedia.org/wiki/Damerau-Levenshtein_distance}
  {Damerau-Levenshtein distance} between \lstinline|this| and
  \var{other}.  The more alike the strings are, the smaller the
  distance is.
\begin{urbiscript}[firstnumber=last]
assert("foo".distance("foo") == 0);
assert("bar".distance("baz") == 1);
assert("foo".distance("bar") == 3);
\end{urbiscript}

\item \lstinline|fresh|\\
  Return a String that has never been used as an identifier, prefixed
  by \lstinline|this|.  It can safely be used with
  \lstinline|Object.setSlot| and so forth.
\begin{urbiscript}[firstnumber=last]
assert(String.fresh == "_5");
assert("foo".fresh == "foo_6");
\end{urbiscript}

\item \lstinline|replace(\var{from}, \var{to})|\\
  Replace every occurrence of the string \var{from} in
  \lstinline|this| by \var{to}, and return the result.
  \lstinline|this| is not modified.
\begin{urbiscript}[firstnumber=last]
assert("Hello == World!".replace("Hello", "Bonjour")
                      .replace("World!", "Monde !"),
       "Bonjour, Monde !");
\end{urbiscript}

\item \lstinline|size|\\
  Return the size of the string.
\begin{urbiscript}[firstnumber=last]
assert("foo".size == 3);
assert("".size == 0);
\end{urbiscript}

\item \lstinline|toLower|\\
  Make lower case every upper case character in \lstinline|this| and
  return the result.  \lstinline|this| is not modified.
\begin{urbiscript}[firstnumber=last]
assert("Hello == World!".toLower, "hello, world!");
\end{urbiscript}

\item \lstinline|toUpper|\\
  Make upper case every lower case character in \lstinline|this| and
  return the result.  \lstinline|this| is not modified.
\begin{urbiscript}[firstnumber=last]
assert("Hello == World!".toUpper, "HELLO, WORLD!");
\end{urbiscript}

\item \lstinline|'%'(\var{args})|\\
  Use \lstinline|this| as format string, and convert occurrences of
  \lstinline|%s| in \lstinline|this| by the \var{args} converted as
  strings via \lstinline|asString|.
%  This construct is actually more
%  powerful than this, since it relies on
%  \href{http://www.boost.org/doc/libs/1_39_0/libs/format/doc/format.html,
%    Boost.Format}.  For instance:
\begin{urbiscript}[firstnumber=last]
assert("%s + %s = %s" % [1, 2, 3] == "1 + 2 = 3");
\end{urbiscript}

\item \lstinline|'*'(\var{n})|\\
  Return the concatentation of \lstinline|this| \var{n} times.
\begin{urbiscript}[firstnumber=last]
assert("foo" * 0 == "");
assert("foo" * 1 == "foo");
assert("foo" * 3 == "foofoofoo");
\end{urbiscript}

\item \lstinline|'+'(\var{other})|\\
  Return the concatenation of \lstinline|this| and
  \lstinline|\var{other}.asString|.
\begin{urbiscript}[firstnumber=last]
assert("foo" + "bar" == "foobar");
assert("foo" + "" == "foo");
assert("foo" + 3 == "foo3");
assert("foo" + [1 == 2, 3], "foo[1, 2, 3]");
\end{urbiscript}

\item \lstinline|'<'(\var{other})|\\
  Whether \lstinline|this| is lexicographically before \var{other},
  which must be a String.
\begin{urbiscript}[firstnumber=last]
assert("" < "a");
assert(!("a" < ""));
assert("a" < "b");
assert(!("a" < "a"));
\end{urbiscript}

\item \lstinline|'[]'(\var{from})|\\
  \lstinline|'[]'(\var{from}, \var{to})|\\
  Return the substring starting at \var{from}, up to and not including
  \var{to} (which defaults to \var{to} + 1).
\begin{urbiscript}[firstnumber=last]
assert("foobar"[0 == 3], "foo");
assert("foobar"[0] == "f");
\end{urbiscript}

\item \lstinline|'[]='(\var{from}, \var{other})|\\
  \lstinline|'[]='(\var{from}, \var{to}, \var{other})|\\
  Replace the substring starting at \var{from}, up to and not including
  \var{to} (which defaults to \var{to} + 1), by \var{other}.  Return
  \var{other}.

  Beware that this routine is imperative: it changes the value of
  \lstinline|this|.
\begin{urbiscript}[firstnumber=last]
var s1 = "foobar" | var s2 = s1 |
assert(s1[0 == 3] = "quux", "quux");
assert(s1 == "quuxbar");
assert(s2 == "quuxbar");
assert(s1[4 == 7] = "", "");
assert(s2 == "quux");
\end{urbiscript}
\end{itemize}

%%% Local Variables:
%%% mode: latex
%%% TeX-master: "../urbi-sdk"
%%% End:

{'fraction_non_alphanumeric': 0.19529329118370214, 'fraction_numerical': 0.02476290832455216, 'mean_word_length': 4.677467597208375, 'pattern_counts': {'":': 0, '<': 13, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 16, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6846081', 'n_tokens_mistral': 4378, 'n_tokens_neox': 4120, 'n_words': 1028}