Merge deno_std in main repo (#3091)

The history of deno_std is persevered but rewritten to update links to issues and PRs

Fixes denoland/deno_std#603

2 files changed, 211 insertions, 0 deletions

diff --git a/std b/std
deleted file mode 160000
-Subproject 43aafbf33285753e7b42230f0eb7969b300f71c
diff --git a/std/fmt/README.md b/std/fmt/README.md
new file mode 100644
index 000000000..8229a585c
--- /dev/null
+++ b/std/fmt/README.md
@@ -0,0 +1,211 @@
+# Printf for Deno
+
+This is very much a work-in-progress. I'm actively soliciting feedback. What
+immediately follows are points for discussion.
+
+If you are looking for the documentation proper, skip to:
+
+    "printf: prints formatted output"
+
+below.
+
+## Discussion
+
+This is very much a work-in-progress. I'm actively soliciting feedback.
+
+- What useful features are available in other languages apart from Golang and C?
+
+- behaviour of `%v` verb. In Golang, this is a shortcut verb to "print the
+  default format" of the argument. It is currently implemented to format using
+  `toString` in the default case and `inpect` if the `%#v` alternative format
+  flag is used in the format directive. Alternativly, `%V` could be used to
+  distinguish the two.
+
+  `inspect` output is not defined, however. This may be problematic if using
+  this code on other plattforms (and expecting interoperability). To my
+  knowledge, no suitable specification of object representation aside from JSON
+  and `toString` exist. ( Aside: see "[Common object formats][3]" in the
+  "Console Living Standard" which basically says "do whatever" )
+
+- `%j` verb. This is an extension particular to this implementation. Currently
+  not very sophisticated, it just runs `JSON.stringify` on the argument.
+  Consider possible modifier flags, etc.
+
+- `<` verb. This is an extension that assumes the argument is an array and will
+  format each element according to the format (surrounded by [] and seperated by
+  comma) (`<` Mnemonic: pull each element out of array)
+
+- how to deal with more newfangled Javascript features ( generic Iterables, Map
+  and Set types, typed Arrays, ...)
+
+- the implementation is fairly rough around the edges:
+
+- currently contains little in the way of checking for correctness. Conceivably,
+  there will be a 'strict' form, e.g. that ensures only Number-ish arguments are
+  passed to %f flags
+
+- assembles output using string concatenation instead of utilizing buffers or
+  other optimizations. It would be nice to have printf / sprintf / fprintf (etc)
+  all in one.
+
+- float formatting is handled by toString() and to `toExponential` along with a
+  mess of Regexp. Would be nice to use fancy match
+
+- some flags that are potentially applicable ( POSIX long and unsigned modifiers
+  are not likely useful) are missing, namely %q (print quoted), %U (unicode
+  format)
+
+## Author
+
+Tim Becker (tim@presseverykey.com)
+
+## License
+
+MIT
+
+The implementation is inspired by POSIX and Golang (see above) but does not port
+implementation code. A number of Golang test-cases based on:
+
+    https://golang.org/src/fmt/fmt_test.go
+    ( BSD: Copyright (c) 2009 The Go Authors. All rights reserved. )
+
+were used.
+
+# printf: prints formatted output
+
+sprintf converts and formats a variable number of arguments as is specified by a
+`format string`. In it's basic form, a format string may just be a literal. In
+case arguments are meant to be formatted, a `directive` is contained in the
+format string, preceded by a '%' character:
+
+    %<verb>
+
+E.g. the verb `s` indicates the directive should be replaced by the string
+representation of the argument in the corresponding position of the argument
+list. E.g.:
+
+    Hello %s!
+
+applied to the arguments "World" yields "Hello World!"
+
+The meaning of the format string is modelled after [POSIX][1] format strings as
+well as well as [Golang format strings][2]. Both contain elements specific to
+the respective programming language that don't apply to JavaScript, so they can
+not be fully supported. Furthermore we implement some functionality that is
+specific to JS.
+
+## Verbs
+
+The following verbs are supported:
+
+| Verb  | Meaning                                                        |
+| ----- | -------------------------------------------------------------- |
+| `%`   | print a literal percent                                        |
+| `t`   | evaluate arg as boolean, print `true` or `false`               |
+| `b`   | eval as number, print binary                                   |
+| `c`   | eval as number, print character corresponding to the codePoint |
+| `o`   | eval as number, print octal                                    |
+| `x X` | print as hex (ff FF), treat string as list of bytes            |
+| `e E` | print number in scientific/exponent format 1.123123e+01        |
+| `f F` | print number as float with decimal point and no exponent       |
+| `g G` | use %e %E or %f %F depending on size of argument               |
+| `s`   | interpolate string                                             |
+| `T`   | type of arg, as returned by `typeof`                           |
+| `v`   | value of argument in 'default' format (see below)              |
+| `j`   | argument as formatted by `JSON.stringify`                      |
+
+## Width and Precision
+
+Verbs may be modified by providing them with width and precision, either or both
+may be omitted:
+
+    %9f    width 9, default precision
+    %.9f   default width, precision 9
+    %8.9f  width 8, precision 9
+    %8.f   width 9, precision 0
+
+In general, 'width' describes the minimum length of the output, while
+'precision' limits the output.
+
+| verb      | precision                                                      |
+| --------- | -------------------------------------------------------------- |
+| `t`       | n/a                                                            |
+| `b c o`   | n/a                                                            |
+| `x X`     | n/a for number, strings are truncated to p bytes(!)            |
+| `e E f F` | number of places after decimal, default 6                      |
+| `g G`     | set maximum number of digits                                   |
+| `s`       | truncate input                                                 |
+| `T`       | truncate                                                       |
+| `v`       | tuncate, or depth if used with # see "'default' format", below |
+| `j`       | n/a                                                            |
+
+Numerical values for width and precision can be substituted for the `*` char, in
+which case the values are obtained from the next args, e.g.:
+
+    sprintf ("%*.*f", 9,8,456.0)
+
+is equivalent to
+
+    sprintf ("%9.9f", 456.0)
+
+## Flags
+
+The effects of the verb may be further influenced by using flags to modify the
+directive:
+
+| Flag  | Verb      | Meaning                                                                    |
+| ----- | --------- | -------------------------------------------------------------------------- |
+| `+`   | numeric   | always print sign                                                          |
+| `-`   | all       | pad to the right (left justify)                                            |
+| `#`   |           | alternate format                                                           |
+| `#`   | `b o x X` | prefix with `0b 0 0x`                                                      |
+| `#`   | `g G`     | don't remove trailing zeros                                                |
+| `#`   | `v`       | ues output of `inspect` instead of `toString`                              |
+| `' '` |           | space character                                                            |
+| `' '` | `x X`     | leave spaces between bytes when printing string                            |
+| `' '` | `d`       | insert space for missing `+` sign character                                |
+| `0`   | all       | pad with zero, `-` takes precedence, sign is appended in front of padding  |
+| `<`   | all       | format elements of the passed array according to the directive (extension) |
+
+## 'default' format
+
+The default format used by `%v` is the result of calling `toString()` on the
+relevant argument. If the `#` flags is used, the result of calling `inspect()`
+is interpolated. In this case, the precision, if set is passed to `inspect()` as
+the 'depth' config parameter
+
+## Positional arguments
+
+Arguments do not need to be consumed in the order they are provded and may be
+consumed more than once. E.g.:
+
+    sprintf("%[2]s %[1]s", "World", "Hello")
+
+returns "Hello World". The precence of a positional indicator resets the arg
+counter allowing args to be reused:
+
+    sprintf("dec[%d]=%d hex[%[1]d]=%x oct[%[1]d]=%#o %s", 1, 255, "Third")
+
+returns `dec[1]=255 hex[1]=0xff oct[1]=0377 Third`
+
+Width and precision my also use positionals:
+
+    "%[2]*.[1]*d", 1, 2
+
+This follows the golang conventions and not POSIX.
+
+## Errors
+
+The following errors are handled:
+
+Incorrect verb:
+
+    S("%h", "") %!(BAD VERB 'h')
+
+Too few arguments:
+
+    S("%d") %!(MISSING 'd')"
+
+[1]: https://pubs.opengroup.org/onlinepubs/009695399/functions/fprintf.html
+[2]: https://golang.org/pkg/fmt/
+[3]: https://console.spec.whatwg.org/#object-formats