•ParseFloat spec

2 files changed, 14 insertions, 6 deletions

diff --git a/docs/spec/system.html b/docs/spec/system.html
index 87a7f942..6ec964f5 100644
--- a/docs/spec/system.html
+++ b/docs/spec/system.html
@@ -369,10 +369,15 @@
 <td><code><span class='Function'>•Fmt</span></code></td>
 <td>Format value for printing</td>
 </tr>
+<tr>
+<td><code><span class='Function'>•ParseFloat</span></code></td>
+<td>Convert from string to floating point number</td>
+</tr>
 </tbody>
 </table>
 <p><code><span class='Function'>•Out</span></code> prints a string to stdout, with a trailing newline. <code><span class='Function'>•Show</span></code> displays a BQN value to the programmer (the representation is not specified, and does not need to be plain text). <code><span class='Function'>•Fmt</span></code> returns a string (not a character table: lines are separated by linefeeds) indicating how <code><span class='Value'>𝕩</span></code> would be printed by the interactive environment. Both <code><span class='Function'>•Show</span></code> and <code><span class='Function'>•Fmt</span></code> may take a left argument configuring how the value should be formatted.</p>
 <p><code><span class='Function'>•Repr</span></code> attempts to return a string so that <code><span class='Function'>•BQN</span> <span class='Function'>•Repr</span> <span class='Value'>𝕩</span></code> matches <code><span class='Value'>𝕩</span></code>. If <code><span class='Value'>𝕩</span></code> contains any mutable values (operations or namespaces), this is not possible. However, if such a values is stateless, in the sense that they don't access variables outside of their own scopes, it is permissible for <code><span class='Function'>•Repr</span></code> to return source code that would create a value with identical behavior.</p>
+<p><code><span class='Function'>•ParseFloat</span></code> returns the numeric value given by a string <code><span class='Value'>𝕩</span></code> in integer, decimal, or scientific notation. The whole of <code><span class='Value'>𝕩</span></code> must match the regular expression <code><span class='Function'>-</span><span class='Head'>?</span><span class='Paren'>(</span><span class='Value'>\.</span><span class='Bracket'>[</span><span class='Number'>0</span><span class='Function'>-</span><span class='Number'>9</span><span class='Bracket'>]</span><span class='Function'>+|</span><span class='Bracket'>[</span><span class='Number'>0</span><span class='Function'>-</span><span class='Number'>9</span><span class='Bracket'>]</span><span class='Function'>+</span><span class='Value'>\.</span><span class='Head'>?</span><span class='Bracket'>[</span><span class='Number'>0</span><span class='Function'>-</span><span class='Number'>9</span><span class='Bracket'>]</span><span class='Value'>*</span><span class='Paren'>)(</span><span class='Bracket'>[</span><span class='Value'>eE</span><span class='Bracket'>][</span><span class='Function'>-+</span><span class='Bracket'>]</span><span class='Head'>?</span><span class='Bracket'>[</span><span class='Number'>0</span><span class='Function'>-</span><span class='Number'>9</span><span class='Bracket'>]</span><span class='Function'>+</span><span class='Paren'>)</span><span class='Head'>?</span></code> or an error is given. This format is similar to BQN's numeric literals but with many differences. Only <code><span class='Function'>-</span></code> (not <code><span class='Number'>¯</span></code>) can be used for a negative sign, and a positive exponent may be optionally preceded by <code><span class='Function'>+</span></code>. A dot <code><span class='Value'>.</span></code> indicates the decimal regardless of locale. The function should make an effort to return the nearest possible value to the exact one represented, but is not required to round perfectly in all cases.</p>
 <h3 id="terminal-io"><a class="header" href="#terminal-io">Terminal I/O</a></h3>
 <p>The system namespace <code><span class='Value'>•term</span></code> gives fine-grained control of input and output when running in a terminal emulator or similar text-based interface.</p>
 <table>
diff --git a/spec/system.md b/spec/system.md
index ffd93d1b..21ad04fc 100644
--- a/spec/system.md
+++ b/spec/system.md
@@ -159,17 +159,20 @@ Not yet specified.
 
 ## Input and output
 
-| Name    | Summary
-|---------|----------------------
-| `•Out`  | Print argument string
-| `•Show` | Print argument value
-| `•Repr` | String representation of `𝕩`, if possible
-| `•Fmt`  | Format value for printing
+| Name          | Summary
+|---------------|----------------------
+| `•Out`        | Print argument string
+| `•Show`       | Print argument value
+| `•Repr`       | String representation of `𝕩`, if possible
+| `•Fmt`        | Format value for printing
+| `•ParseFloat` | Convert from string to floating point number
 
 `•Out` prints a string to stdout, with a trailing newline. `•Show` displays a BQN value to the programmer (the representation is not specified, and does not need to be plain text). `•Fmt` returns a string (not a character table: lines are separated by linefeeds) indicating how `𝕩` would be printed by the interactive environment. Both `•Show` and `•Fmt` may take a left argument configuring how the value should be formatted.
 
 `•Repr` attempts to return a string so that `•BQN •Repr 𝕩` matches `𝕩`. If `𝕩` contains any mutable values (operations or namespaces), this is not possible. However, if such a values is stateless, in the sense that they don't access variables outside of their own scopes, it is permissible for `•Repr` to return source code that would create a value with identical behavior.
 
+`•ParseFloat` returns the numeric value given by a string `𝕩` in integer, decimal, or scientific notation. The whole of `𝕩` must match the regular expression `-?(\.[0-9]+|[0-9]+\.?[0-9]*)([eE][-+]?[0-9]+)?` or an error is given. This format is similar to BQN's numeric literals but with many differences. Only `-` (not `¯`) can be used for a negative sign, and a positive exponent may be optionally preceded by `+`. A dot `.` indicates the decimal regardless of locale. The function should make an effort to return the nearest possible value to the exact one represented, but is not required to round perfectly in all cases.
+
 ### Terminal I/O
 
 The system namespace `•term` gives fine-grained control of input and output when running in a terminal emulator or similar text-based interface.