From a97a7c5eb6e0bca13076c3ce40c8c1f1f020cca6 Mon Sep 17 00:00:00 2001 From: Rob Pike Date: Thu, 12 Sep 2013 09:08:59 +1000 Subject: [PATCH] doc/go1.2.html: some library changes (fmt, template) Also link it to the landing page for docs. R=golang-dev, adg CC=golang-dev https://golang.org/cl/13652045 --- doc/docs.html | 6 ++ doc/go1.2.html | 224 ++++++++++++++++++++++++++++++++++++------------- 2 files changed, 172 insertions(+), 58 deletions(-) diff --git a/doc/docs.html b/doc/docs.html index 2dcab5d51c..32ce1d63bc 100644 --- a/doc/docs.html +++ b/doc/docs.html @@ -88,6 +88,12 @@ A list of significant changes in Go 1.1, with instructions for updating your code where necessary.

+

Go 1.2 Release Notes

+

+A list of significant changes in Go 1.2, with instructions for updating your +code where necessary. +

+

Go 1 and the Future of Go Programs

What Go 1 defines and the backwards-compatibility guarantees one can expect as diff --git a/doc/go1.2.html b/doc/go1.2.html index c3d5466cbc..8d513997ee 100644 --- a/doc/go1.2.html +++ b/doc/go1.2.html @@ -163,7 +163,7 @@ no client code depends on the godoc sources and no updating is required.

-The binary distributions available from golang.org include a godoc binary, so users of these distributions are unaffected.

@@ -269,83 +269,176 @@ to list them all here, but the following major changes are worth noting:

Changes to the standard library

-

foo.Bar

+ +

The archive/tar and archive/zip packages

-TODO: choose which to call out - -The various routines to scan textual input in the -bufio -package, -ReadBytes, -ReadString -and particularly -ReadLine, -are needlessly complex to use for simple purposes. -In Go 1.1, a new type, -Scanner, -has been added to make it easier to do simple tasks such as -read the input as a sequence of lines or space-delimited words. -It simplifies the problem by terminating the scan on problematic -input such as pathologically long lines, and having a simple -default: line-oriented input, with each line stripped of its terminator. -Here is code to reproduce the input a line at a time: - +Breaking change: TODO +archive/tar,archive/zip: fix os.FileInfo implementation to provide base name only (CL 13118043). +

+ +

The new encoding package

- -Updating: -To correct breakage caused by the new struct field, -go fix will rewrite code to add tags for these types. -More generally, go vet will identify composite literals that -should be revised to use field tags. - +encoding: TODO new package defining generic encoding interfaces (CL 12541051).

- +
+fmt.Sprintf("%[3]c %[1]c %c\n", 'a', 'b', 'c')
+
+ +

+the result is ""c a b". The [3] index accesses the third formatting +argument, whch is 'c', [1] accesses the first, 'a', +and then the next fetch accesses the argument following that one, 'b'. +

+ +

+The motivation for this feature is programmable format statements to access +the arguments in different order for localization, but it has other uses: +

+ +
+log.Printf("trace: value %v of type %[1]T\n", expensiveFunction(a.b[c]))
+
+ +

+Updating: The change to the syntax of format specifications +is strictly backwards compatible, so it affects no working programs. +

+ +

The text/template and html/template packages

+ +

+The +text/template package +has a couple of changes in Go 1.2, both of which are also mirrored in the +html/template package. +

+ +

+First, there are new default functions for comparing basic types. +The functions are listed in this table, which shows their names and +the associated familiar comparison operator. +

+ + + + + + + + + + + + + + + + + + + + + + + +
Name Operator
eq ==
ne !=
lt <
le <=
gt >
ge >=
+ +

+These functions behave slightly differently from the corresponding Go operators. +First, they operate only on basic types (bool, int, +float64, string, etc.). +(Go allows comparison of arrays and structs as well, under some circumstances.) +Second, values can be compared as long as they are the same sort of value: +any signed integer value can be compared to any other signed integer value for example. (Go +does not permit comparing an int8 and an int16). +Finally, the eq function (only) allows comparison of the first +argument with one or more following arguments. The template in this example, +

+ +
+{{"{{"}}if eq .A 1 2 3 {{"}}"}} equal {{"{{"}}else{{"}}"}} not equal {{"{{"}}end{{"}}"}}
+
+ +

+reports "equal" if .A is equal to any of 1, 2, or 3. +

+ +

+The second change is that a small addition to the grammar makes "if else if" chains easier to write. +Instead of writing, +

+ +
+{{"{{"}}if eq .A 1{{"}}"}} X {{"{{"}}else{{"}}"}} {{"{{"}}if eq .A 2{{"}}"}} Y {{"{{"}}end{{"}}"}} {{"{{"}}end{{"}}"}} 
+
+ +

+one can fold the second "if" into the "else" and have only one "end", like this: +

+ +
+{{"{{"}}if eq .A 1{{"}}"}} X {{"{{"}}else if eq .A 2{{"}}"}} Y {{"{{"}}end{{"}}"}}
+
+ +

+The two forms are identical in effect; the difference is just in the syntax. +

+ +

+Updating: Neither change affects existing programs. Those that +already define functions called eq and so on through a function +map are unaffected because the associated function map will override the new +default function definitions. +

Minor changes to the library

@@ -556,19 +649,19 @@ so that less intermediate buffering is required in general.
  • -net: new build tag netgo for building a pure Go net package (CL 7100050). +net: TODO new build tag netgo for building a pure Go net package (CL 7100050).
  • -net/http: don't allow sending invalid cookie lines (CL 12204043). +net/http: TODO don't allow sending invalid cookie lines (CL 12204043).
  • -net/http: allow ReadResponse with nil *Request parameter (CL 9821043). +net/http: TODO allow ReadResponse with nil *Request parameter (CL 9821043).
  • -net/http: allow responses to HEAD requests, detect type and length (CL 12583043). +net/http: TODO allow responses to HEAD requests, detect type and length (CL 12583043).
  • @@ -591,6 +684,21 @@ an IndexByte function for consistency with the bytes package.
    • +
  • +The sync/atomic package +adds a new set of swap functions that atomically exchange the argument with the +value stored in the pointer, returning the old value. +The functions are +SwapInt32, +SwapInt64, +SwapUint32, +SwapUint64, +SwapUintptr, +and +SwapPointer, +which swaps an unsafe.Pointer. +
    • +
  • syscall: implemented Sendfile for Darwin, added Syscall9 for Darwin/amd64 (CL 10980043).
    • -- 2.52.0