summaryrefslogtreecommitdiff
path: root/doc/go1.1.html
blob: 87d5f5c8768685ac36be6d8324bf2507d4fc6788 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
<!--{
	"Title": "Go 1.1 Release Notes",
	"Path":  "/doc/go1.1",
	"Template": true
}-->

<h2 id="introduction">Introduction to Go 1.1</h2>

<p>
The release of <a href="/doc/go1.html">Go version 1</a> (Go 1 or Go 1.0 for short)
in March of 2012 introduced a new period
of stability in the Go language and libraries.
That stability has helped nourish a growing community of Go users
and systems around the world.
Several "point" releases since
then—1.0.1, 1.0.2, and 1.0.3—have been issued.
These point releases fixed known bugs but made
no non-critical changes to the implementation.
</p>

<p>
This new release, Go 1.1, keeps the <a href="/doc/go1compat.html">promise
of compatibility</a> but adds a couple of significant
(backwards-compatible, of course) language changes, has a long list
of (again, compatible) library changes, and
includes major work on the implementation of the compilers,
libraries, and run-time.
The focus is on performance.
Benchmarking is an inexact science at best, but we see significant,
sometimes dramatic speedups for many of our test programs.
We trust that many of our users' programs will also see improvements
just by updating their Go installation and recompiling.
</p>

<p>
This document summarizes the changes between Go 1 and Go 1.1.
Very little if any code will need modification to run with Go 1.1,
although a couple of rare error cases surface with this release
and need to be addressed if they arise.
Details appear below; see the discussion of
<a href="#int">64-bit ints</a> and <a href="#unicode_literals">Unicode literals</a>
in particular.
</p>

<h2 id="language">Changes to the language</h2>

<p>
<a href="/doc/go1compat.html">The Go compatibility document</a> promises
that programs written to the Go 1 language specification will continue to operate,
and those promises are maintained.
In the interest of firming up the specification, though, there are
details about some error cases that have been clarified.
There are also some new language features.
</p>

<h3 id="divzero">Integer division by zero</h3>

<p>
In Go 1, integer division by a constant zero produced a run-time panic:
</p>

<pre>
func f(x int) int {
	return x/0
}
</pre>

<p>
In Go 1.1, an integer division by constant zero is not a legal program, so it is a compile-time error.
</p>

<h3 id="unicode_literals">Surrogates in Unicode literals</h3>

<p>
The definition of string and rune literals has been refined to exclude surrogate halves from the
set of valid Unicode code points.
See the <a href="#unicode">Unicode</a> section for more information.
</p>

<h3 id="method_values">Method values</h3>

<p>
Go 1.1 now implements
<a href="/ref/spec#Method_values">method values</a>,
which are functions that have been bound to a specific receiver value.
For instance, given a
<a href="/pkg/bufio/#Writer"><code>Writer</code></a>
value <code>w</code>,
the expression
<code>w.Write</code>,
a method value, is a function that will always write to <code>w</code>; it is equivalent to
a function literal closing over <code>w</code>:
</p>

<pre>
func (p []byte) (n int, err error) {
	return w.Write(p)
}
</pre>

<p>
Method values are distinct from method expressions, which generate functions
from methods of a given type; the method expression <code>(*bufio.Writer).Write</code>
is equivalent to a function with an extra first argument, a receiver of type
<code>(*bufio.Writer)</code>:
</p>

<pre>
func (w *bufio.Writer, p []byte) (n int, err error) {
	return w.Write(p)
}
</pre>

<p>
<em>Updating</em>: No existing code is affected; the change is strictly backward-compatible.
</p>

<h3 id="return">Return requirements</h3>

<p>
Before Go 1.1, a function that returned a value needed an explicit "return"
or call to <code>panic</code> at
the end of the function; this was a simple way to make the programmer
be explicit about the meaning of the function. But there are many cases
where a final "return" is clearly unnecessary, such as a function with
only an infinite "for" loop.
</p>

<p>
In Go 1.1, the rule about final "return" statements is more permissive.
It introduces the concept of a
<a href="/ref/spec#Terminating_statements"><em>terminating statement</em></a>,
a statement that is guaranteed to be the last one a function executes.
Examples include
"for" loops with no condition and "if-else"
statements in which each half ends in a "return".
If the final statement of a function can be shown <em>syntactically</em> to
be a terminating statement, no final "return" statement is needed.
</p>

<p>
Note that the rule is purely syntactic: it pays no attention to the values in the
code and therefore requires no complex analysis.
</p>

<p>
<em>Updating</em>: The change is backward-compatible, but existing code
with superfluous "return" statements and calls to <code>panic</code> may
be simplified manually.
Such code can be identified by <code>go vet</code>.
</p>

<h2 id="impl">Changes to the implementations and tools</h2>

<h3 id="gccgo">Status of gccgo</h3>

<p>
The GCC release schedule does not coincide with the Go release schedule, so some skew is inevitable in
<code>gccgo</code>'s releases.
The 4.8.0 version of GCC shipped in March, 2013 and includes a nearly-Go 1.1 version of <code>gccgo</code>.
Its library is a little behind the release, but the biggest difference is that method values are not implemented.
Sometime around July 2013, we expect 4.8.2 of GCC to ship with a <code>gccgo</code>
providing a complete Go 1.1 implementaiton.
</p>

<h3 id="gc_flag">Command-line flag parsing</h3>

<p>
In the gc tool chain, the compilers and linkers now use the
same command-line flag parsing rules as the Go flag package, a departure
from the traditional Unix flag parsing. This may affect scripts that invoke
the tool directly.
For example,
<code>go tool 6c -Fw -Dfoo</code> must now be written
<code>go tool 6c -F -w -D foo</code>.
</p>

<h3 id="int">Size of int on 64-bit platforms</h3>

<p>
The language allows the implementation to choose whether the <code>int</code> type and
<code>uint</code> types are 32 or 64 bits. Previous Go implementations made <code>int</code>
and <code>uint</code> 32 bits on all systems. Both the gc and gccgo implementations
now make
<code>int</code> and <code>uint</code> 64 bits on 64-bit platforms such as AMD64/x86-64.
Among other things, this enables the allocation of slices with
more than 2 billion elements on 64-bit platforms.
</p>

<p>
<em>Updating</em>:
Most programs will be unaffected by this change.
Because Go does not allow implicit conversions between distinct
<a href="/ref/spec#Numeric_types">numeric types</a>,
no programs will stop compiling due to this change.
However, programs that contain implicit assumptions
that <code>int</code> is only 32 bits may change behavior.
For example, this code prints a positive number on 64-bit systems and
a negative one on 32-bit systems:
</p>

<pre>
x := ^uint32(0) // x is 0xffffffff
i := int(x)     // i is -1 on 32-bit systems, 0xffffffff on 64-bit
fmt.Println(i)
</pre>

<p>Portable code intending 32-bit sign extension (yielding <code>-1</code> on all systems)
would instead say:
</p>

<pre>
i := int(int32(x))
</pre>

<h3 id="heap">Heap size on 64-bit architectures</h3>

<p>
On 64-bit architectures, the maximum heap size has been enlarged substantially,
from a few gigabytes to several tens of gigabytes.
(The exact details depend on the system and may change.)
</p>

<p>
On 32-bit architectures, the heap size has not changed.
</p>

<p>
<em>Updating</em>:
This change should have no effect on existing programs beyond allowing them
to run with larger heaps.
</p>

<h3 id="unicode">Unicode</h3>

<p>
To make it possible to represent code points greater than 65535 in UTF-16,
Unicode defines <em>surrogate halves</em>,
a range of code points to be used only in the assembly of large values, and only in UTF-16.
The code points in that surrogate range are illegal for any other purpose.
In Go 1.1, this constraint is honored by the compiler, libraries, and run-time:
a surrogate half is illegal as a rune value, when encoded as UTF-8, or when
encoded in isolation as UTF-16.
When encountered, for example in converting from a rune to UTF-8, it is
treated as an encoding error and will yield the replacement rune,
<a href="/pkg/unicode/utf8/#RuneError"><code>utf8.RuneError</code></a>,
U+FFFD.
</p>

<p>
This program,
</p>

<pre>
import "fmt"

func main() {
    fmt.Printf("%+q\n", string(0xD800))
}
</pre>

<p>
printed <code>"\ud800"</code> in Go 1.0, but prints <code>"\ufffd"</code> in Go 1.1.
</p>

<p>
Surrogate-half Unicode values are now illegal in rune and string constants, so constants such as
<code>'\ud800'</code> and <code>"\ud800"</code> are now rejected by the compilers.
When written explicitly as UTF-8 encoded bytes,
such strings can still be created, as in <code>"\xed\xa0\x80"</code>.
However, when such a string is decoded as a sequence of runes, as in a range loop, it will yield only <code>utf8.RuneError</code>
values.
</p>

<p>
The Unicode byte order mark U+FEFF, encoded in UTF-8, is now permitted as the first
character of a Go source file.
Even though its appearance in the byte-order-free UTF-8 encoding is clearly unnecessary,
some editors add the mark as a kind of "magic number" identifying a UTF-8 encoded file.
</p>

<p>
<em>Updating</em>:
Most programs will be unaffected by the surrogate change.
Programs that depend on the old behavior should be modified to avoid the issue.
The byte-order-mark change is strictly backward-compatible.
</p>

<h3 id="race">Race detector</h3>

<p>
A major addition to the tools is a <em>race detector</em>, a way to
find bugs in programs caused by concurrent access of the same
variable, where at least one of the accesses is a write.
This new facility is built into the <code>go</code> tool.
For now, it is only available on Linux, Mac OS X, and Windows systems with
64-bit x86 processors.
To enable it, set the <code>-race</code> flag when building or testing your program
(for instance, <code>go test -race</code>).
The race detector is documented in <a href="/doc/articles/race_detector.html">a separate article</a>.
</p>

<h3 id="gc_asm">The gc assemblers</h3>

<p>
Due to the change of the <a href="#int"><code>int</code></a> to 64 bits and
a new internal <a href="http://golang.org/s/go11func">representation of functions</a>,
the arrangement of function arguments on the stack has changed in the gc tool chain.
Functions written in assembly will need to be revised at least
to adjust frame pointer offsets.
</p>

<p>
<em>Updating</em>:
The <code>go vet</code> command now checks that functions implemented in assembly
match the Go function prototypes they implement.
</p>

<h3 id="gocmd">Changes to the go command</h3>

<p>
The <a href="/cmd/go/"><code>go</code></a> command has acquired several
changes intended to improve the experience for new Go users.
</p>

<p>
First, when compiling, testing, or running Go code, the <code>go</code> command will now give more detailed error messages,
including a list of paths searched, when a package cannot be located.
</p>

<pre>
$ go build foo/quxx
can't load package: package foo/quxx: cannot find package "foo/quxx" in any of:
        /home/you/go/src/pkg/foo/quxx (from $GOROOT)
        /home/you/src/foo/quxx (from $GOPATH)
</pre>

<p>
Second, the <code>go get</code> command no longer allows <code>$GOROOT</code>
as the default destination when downloading package source.
To use the <code>go get</code>
command, a <a href="/doc/code.html#GOPATH">valid <code>$GOPATH</code></a> is now required.
</p>

<pre>
$ GOPATH= go get code.google.com/p/foo/quxx
package code.google.com/p/foo/quxx: cannot download, $GOPATH not set. For more details see: go help gopath
</pre>

<p>
Finally, as a result of the previous change, the <code>go get</code> command will also fail
when <code>$GOPATH</code> and <code>$GOROOT</code> are set to the same value.
</p>

<pre>
$ GOPATH=$GOROOT go get code.google.com/p/foo/quxx
warning: GOPATH set to GOROOT (/home/you/go) has no effect
package code.google.com/p/foo/quxx: cannot download, $GOPATH must not be set to $GOROOT. For more details see: go help gopath
</pre>

<h3 id="gotest">Changes to the go test command</h3>

<p>
The <a href="/cmd/go/#hdr-Test_packages"><code>go test</code></a>
command no longer deletes the binary when run with profiling enabled,
to make it easier to analyze the profile.
The implementation sets the <code>-c</code> flag automatically, so after running,
</p>

<pre>
$ go test -cpuprofile cpuprof.out mypackage
</pre>

<p>
the file <code>mypackage.test</code> will be left in the directory where <code>go test</code> was run.
</p>

<p>
The <a href="/cmd/go/#hdr-Test_packages"><code>go test</code></a>
command can now generate profiling information
that reports where goroutines are blocked, that is,
where they tend to stall waiting for an event such as a channel communication.
The information is presented as a
<em>blocking profile</em>
enabled with the
<code>-blockprofile</code>
option of
<code>go test</code>.
Run <code>go help test</code> for more information.
</p>

<h3 id="gofix">Changes to the go fix command</h3>

<p>
The <a href="/cmd/fix/"><code>fix</code></a> command, usually run as
<code>go fix</code>, no longer applies fixes to update code from
before Go 1 to use Go 1 APIs.
To update pre-Go 1 code to Go 1.1, use a Go 1.0 tool chain
to convert the code to Go 1.0 first.
</p>

<h3 id="tags">Build constraints</h3>

<p>
The "<code>go1.1</code>" tag has been added to the list of default
<a href="/pkg/go/build/#hdr-Build_Constraints">build constraints</a>.
This permits packages to take advantage of the new features in Go 1.1 while
remaining compatible with earlier versions of Go.
</p>

<p>
To build a file only with Go 1.1 and above, add this build constraint:
</p>

<pre>
// +build go1.1
</pre>

<p>
To build a file only with Go 1.0.x, use the converse constraint:
</p>

<pre>
// +build !go1.1
</pre>

<h3 id="platforms">Additional platforms</h3>

<p>
The Go 1.1 tool chain adds experimental support for <code>freebsd/arm</code>,
<code>netbsd/386</code>, <code>netbsd/amd64</code>, <code>netbsd/arm</code>,
<code>openbsd/386</code> and <code>openbsd/amd64</code> platforms.
</p>

<p>
An ARMv6 or later processor is required for <code>freebsd/arm</code> or
<code>netbsd/arm</code>.
</p>

<p>
Go 1.1 adds experimental support for <code>cgo</code> on <code>linux/arm</code>.
</p>

<h3 id="crosscompile">Cross compilation</h3>

<p>
When cross-compiling, the <code>go</code> tool will disable <code>cgo</code>
support by default.
</p>

<p>
To explicitly enable <code>cgo</code>, set <code>CGO_ENABLED=1</code>.
</p>

<h2 id="performance">Performance</h2>

<p>
The performance of code compiled with the Go 1.1 gc tool suite should be noticeably
better for most Go programs.
Typical improvements relative to Go 1.0 seem to be about 30%-40%, sometimes
much more, but occasionally less or even non-existent.
There are too many small performance-driven tweaks through the tools and libraries
to list them all here, but the following major changes are worth noting:
</p>

<ul>
<li>The gc compilers generate better code in many cases, most noticeably for
floating point on the 32-bit Intel architecture.</li>
<li>The gc compilers do more in-lining, including for some operations
in the run-time such as <a href="/pkg/builtin/#append"><code>append</code></a>
and interface conversions.</li>
<li>There is a new implementation of Go maps with significant reduction in
memory footprint and CPU time.</li>
<li>The garbage collector has been made more parallel, which can reduce
latencies for programs running on multiple CPUs.</li>
<li>The garbage collector is also more precise, which costs a small amount of
CPU time but can reduce the size of the heap significantly, especially
on 32-bit architectures.</li>
<li>Due to tighter coupling of the run-time and network libraries, fewer
context switches are required on network operations.</li>
</ul>

<h2 id="library">Changes to the standard library</h2>

<h3 id="bufio_scanner">bufio.Scanner</h3>

<p>
The various routines to scan textual input in the
<a href="/pkg/bufio/"><code>bufio</code></a>
package,
<a href="/pkg/bufio/#Reader.ReadBytes"><code>ReadBytes</code></a>,
<a href="/pkg/bufio/#Reader.ReadString"><code>ReadString</code></a>
and particularly
<a href="/pkg/bufio/#Reader.ReadLine"><code>ReadLine</code></a>,
are needlessly complex to use for simple purposes.
In Go 1.1, a new type,
<a href="/pkg/bufio/#Scanner"><code>Scanner</code></a>,
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:
</p>

<pre>
scanner := bufio.NewScanner(os.Stdin)
for scanner.Scan() {
    fmt.Println(scanner.Text()) // Println will add back the final '\n'
}
if err := scanner.Err(); err != nil {
    fmt.Fprintln(os.Stderr, "reading standard input:", err)
}
</pre>

<p>
Scanning behavior can be adjusted through a function to control subdividing the input
(see the documentation for <a href="/pkg/bufio/#SplitFunc"><code>SplitFunc</code></a>),
but for tough problems or the need to continue past errors, the older interface
may still be required.
</p>

<h3 id="net">net</h3>

<p>
The protocol-specific resolvers in the <a href="/pkg/net/"><code>net</code></a> package were formerly
lax about the network name passed in.
Although the documentation was clear
that the only valid networks for
<a href="/pkg/net/#ResolveTCPAddr"><code>ResolveTCPAddr</code></a>
are <code>"tcp"</code>,
<code>"tcp4"</code>, and <code>"tcp6"</code>, the Go 1.0 implementation silently accepted any string.
The Go 1.1 implementation returns an error if the network is not one of those strings.
The same is true of the other protocol-specific resolvers <a href="/pkg/net/#ResolveIPAddr"><code>ResolveIPAddr</code></a>,
<a href="/pkg/net/#ResolveUDPAddr"><code>ResolveUDPAddr</code></a>, and
<a href="/pkg/net/#ResolveUnixAddr"><code>ResolveUnixAddr</code></a>.
</p>

<p>
The previous implementation of
<a href="/pkg/net/#ListenUnixgram"><code>ListenUnixgram</code></a>
returned a
<a href="/pkg/net/#UDPConn"><code>UDPConn</code></a> as
a representation of the connection endpoint.
The Go 1.1 implementation instead returns a
<a href="/pkg/net/#UnixConn"><code>UnixConn</code></a>
to allow reading and writing
with its
<a href="/pkg/net/#UnixConn.ReadFrom"><code>ReadFrom</code></a>
and
<a href="/pkg/net/#UnixConn.WriteTo"><code>WriteTo</code></a>
methods.
</p>

<p>
The data structures
<a href="/pkg/net/#IPAddr"><code>IPAddr</code></a>,
<a href="/pkg/net/#TCPAddr"><code>TCPAddr</code></a>, and
<a href="/pkg/net/#UDPAddr"><code>UDPAddr</code></a>
add a new string field called <code>Zone</code>.
Code using untagged composite literals (e.g. <code>net.TCPAddr{ip, port}</code>)
instead of tagged literals (<code>net.TCPAddr{IP: ip, Port: port}</code>)
will break due to the new field.
The Go 1 compatibility rules allow this change: client code must use tagged literals to avoid such breakages.
</p>

<p>
<em>Updating</em>:
To correct breakage caused by the new struct field,
<code>go fix</code> will rewrite code to add tags for these types.
More generally, <code>go vet</code> will identify composite literals that
should be revised to use field tags.
</p>

<h3 id="reflect">reflect</h3>

<p>
The <a href="/pkg/reflect/"><code>reflect</code></a> package has several significant additions.
</p>

<p>
It is now possible to run a "select" statement using
the <code>reflect</code> package; see the description of
<a href="/pkg/reflect/#Select"><code>Select</code></a>
and
<a href="/pkg/reflect/#SelectCase"><code>SelectCase</code></a>
for details.
</p>

<p>
The new method
<a href="/pkg/reflect/#Value.Convert"><code>Value.Convert</code></a>
(or
<a href="/pkg/reflect/#Type"><code>Type.ConvertibleTo</code></a>)
provides functionality to execute a Go conversion or type assertion operation
on a
<a href="/pkg/reflect/#Value"><code>Value</code></a>
(or test for its possibility).
</p>

<p>
The new function
<a href="/pkg/reflect/#MakeFunc"><code>MakeFunc</code></a>
creates a wrapper function to make it easier to call a function with existing
<a href="/pkg/reflect/#Value"><code>Values</code></a>,
doing the standard Go conversions among the arguments, for instance
to pass an actual <code>int</code> to a formal <code>interface{}</code>.
</p>

<p>
Finally, the new functions
<a href="/pkg/reflect/#ChanOf"><code>ChanOf</code></a>,
<a href="/pkg/reflect/#MapOf"><code>MapOf</code></a>
and
<a href="/pkg/reflect/#SliceOf"><code>SliceOf</code></a>
construct new
<a href="/pkg/reflect/#Type"><code>Types</code></a>
from existing types, for example to construct the type <code>[]T</code> given
only <code>T</code>.
</p>


<h3 id="time">time</h3>
<p>
On FreeBSD, Linux, NetBSD, OS X and OpenBSD, previous versions of the
<a href="/pkg/time/"><code>time</code></a> package
returned times with microsecond precision.
The Go 1.1 implementation on these
systems now returns times with nanosecond precision.
Programs that write to an external format with microsecond precision
and read it back, expecting to recover the original value, will be affected
by the loss of precision.
There are two new methods of <a href="/pkg/time/#Time"><code>Time</code></a>,
<a href="/pkg/time/#Time.Round"><code>Round</code></a>
and
<a href="/pkg/time/#Time.Truncate"><code>Truncate</code></a>,
that can be used to remove precision from a time before passing it to
external storage.
</p>

<p>
The new method
<a href="/pkg/time/#Time.YearDay"><code>YearDay</code></a>
returns the one-indexed integral day number of the year specified by the time value.
</p>

<p>
The
<a href="/pkg/time/#Timer"><code>Timer</code></a>
type has a new method
<a href="/pkg/time/#Timer.Reset"><code>Reset</code></a>
that modifies the timer to expire after a specified duration.
</p>

<p>
Finally, the new function
<a href="/pkg/time/#ParseInLocation"><code>ParseInLocation</code></a>
is like the existing
<a href="/pkg/time/#Parse"><code>Parse</code></a>
but parses the time in the context of a location (time zone), ignoring
time zone information in the parsed string.
This function addresses a common source of confusion in the time API.
</p>

<p>
<em>Updating</em>:
Code that needs to read and write times using an external format with
lower precision should be modified to use the new methods.
</p>

<h3 id="exp_old">Exp and old subtrees moved to go.exp and go.text subrepositories</h3>

<p>
To make it easier for binary distributions to access them if desired, the <code>exp</code>
and <code>old</code> source subtrees, which are not included in binary distributions,
have been moved to the new <code>go.exp</code> subrepository at
<code>code.google.com/p/go.exp</code>. To access the <code>ssa</code> package,
for example, run
</p>

<pre>
$ go get code.google.com/p/go.exp/ssa
</pre>

<p>
and then in Go source,
</p>

<pre>
import "code.google.com/p/go.exp/ssa"
</pre>

<p>
The old package <code>exp/norm</code> has also been moved, but to a new repository
<code>go.text</code>, where the Unicode APIs and other text-related packages will
be developed.
</p>

<h3 id="new_packages">New packages</h3>

<p>
There are three new packages.
</p>

<ul>
<li>
The <a href="/pkg/go/format/"><code>go/format</code></a> package provides
a convenient way for a program to access the formatting capabilities of the
<a href="/cmd/go/#hdr-Run_gofmt_on_package_sources"><code>go fmt</code></a> command.
It has two functions,
<a href="/pkg/go/format/#Node"><code>Node</code></a> to format a Go parser
<a href="/pkg/go/ast/#Node"><code>Node</code></a>,
and
<a href="/pkg/go/format/#Source"><code>Source</code></a>
to reformat arbitrary Go source code into the standard format as provided by the
<a href="/cmd/go/#hdr-Run_gofmt_on_package_sources"><code>go fmt</code></a> command.
</li>

<li>
The <a href="/pkg/net/http/cookiejar/"><code>net/http/cookiejar</code></a> package provides the basics for managing HTTP cookies.
</li>

<li>
The <a href="/pkg/runtime/race/"><code>runtime/race</code></a> package provides low-level facilities for data race detection.
It is internal to the race detector and does not otherwise export any user-visible functionality.
</li>
</ul>

<h3 id="minor_library_changes">Minor changes to the library</h3>

<p>
The following list summarizes a number of minor changes to the library, mostly additions.
See the relevant package documentation for more information about each change.
</p>

<ul>
<li>
The <a href="/pkg/bytes/"><code>bytes</code></a> package has two new functions,
<a href="/pkg/bytes/#TrimPrefix"><code>TrimPrefix</code></a>
and
<a href="/pkg/bytes/#TrimSuffix"><code>TrimSuffix</code></a>,
with self-evident properties.
Also, the <a href="/pkg/bytes/#Buffer"><code>Buffer</code></a> type
has a new method
<a href="/pkg/bytes/#Buffer.Grow"><code>Grow</code></a> that
provides some control over memory allocation inside the buffer.
Finally, the
<a href="/pkg/bytes/#Reader"><code>Reader</code></a> type now has a
<a href="/pkg/strings/#Reader.WriteTo"><code>WriteTo</code></a> method
so it implements the
<a href="/pkg/io/#WriterTo"><code>io.WriterTo</code></a> interface.
</li>

<li>
The <a href="/pkg/compress/gzip/"><code>compress/gzip</code></a> package has
a new <a href="/pkg/compress/gzip/#Writer.Flush"><code>Flush</code></a>
method for its
<a href="/pkg/compress/gzip/#Writer"><code>Writer</code></a>
type that flushes its underlying <code>flate.Writer</code>.
</li>

<li>
The <a href="/pkg/crypto/hmac/"><code>crypto/hmac</code></a> package has a new function,
<a href="/pkg/crypto/hmac/#Equal"><code>Equal</code></a>, to compare two MACs.
</li>

<li>
The <a href="/pkg/crypto/x509/"><code>crypto/x509</code></a> package
now supports PEM blocks (see
<a href="/pkg/crypto/x509/#DecryptPEMBlock"><code>DecryptPEMBlock</code></a> for instance),
and a new function
<a href="/pkg/crypto/x509/#ParseECPrivateKey"><code>ParseECPrivateKey</code></a> to parse elliptic curve private keys.
</li>

<li>
The <a href="/pkg/database/sql/"><code>database/sql</code></a> package
has a new
<a href="/pkg/database/sql/#DB.Ping"><code>Ping</code></a>
method for its
<a href="/pkg/database/sql/#DB"><code>DB</code></a>
type that tests the health of the connection.
</li>

<li>
The <a href="/pkg/database/sql/driver/"><code>database/sql/driver</code></a> package
has a new
<a href="/pkg/database/sql/driver/#Queryer"><code>Queryer</code></a>
interface that a
<a href="/pkg/database/sql/driver/#Conn"><code>Conn</code></a>
may implement to improve performance.
</li>

<li>
The <a href="/pkg/encoding/json/"><code>encoding/json</code></a> package's
<a href="/pkg/encoding/json/#Decoder"><code>Decoder</code></a>
has a new method
<a href="/pkg/encoding/json/#Decoder.Buffered"><code>Buffered</code></a>
to provide access to the remaining data in its buffer,
as well as a new method
<a href="/pkg/encoding/json/#Decoder.UseNumber"><code>UseNumber</code></a>
to unmarshal a value into the new type
<a href="/pkg/encoding/json/#Number"><code>Number</code></a>,
a string, rather than a float64.
</li>

<li>
The <a href="/pkg/encoding/xml/"><code>encoding/xml</code></a> package
has a new function,
<a href="/pkg/encoding/xml/#EscapeText"><code>EscapeText</code></a>,
which writes escaped XML output,
and a method on
<a href="/pkg/encoding/xml/#Encoder"><code>Encoder</code></a>,
<a href="/pkg/encoding/xml/#Encoder.Indent"><code>Indent</code></a>,
to specify indented output.
</li>

<li>
In the <a href="/pkg/go/ast/"><code>go/ast</code></a> package, a
new type <a href="/pkg/go/ast/#CommentMap"><code>CommentMap</code></a>
and associated methods makes it easier to extract and process comments in Go programs.
</li>

<li>
In the <a href="/pkg/go/doc/"><code>go/doc</code></a> package,
the parser now keeps better track of stylized annotations such as <code>TODO(joe)</code>
throughout the code,
information that the <a href="/cmd/godoc/"><code>godoc</code></a>
command can filter or present according to the value of the <code>-notes</code> flag.
</li>

<li>
The undocumented and only partially implemented "noescape" feature of the
<a href="/pkg/html/template/"><code>html/template</code></a>
package has been removed; programs that depend on it will break.
</li>

<li>
The <a href="/pkg/image/jpeg/"><code>image/jpeg</code></a> package now
reads progressive JPEG files and handles a few more subsampling configurations.
</li>

<li>
The <a href="/pkg/io/"><code>io</code></a> package now exports the
<a href="/pkg/io/#ByteWriter"><code>io.ByteWriter</code></a> interface to capture the common
functionality of writing a byte at a time.
It also exports a new error, <a href="/pkg/io/#ErrNoProgress"><code>ErrNoProgress</code></a>,
used to indicate a <code>Read</code> implementation is looping without delivering data.
</li>

<li>
The <a href="/pkg/log/syslog/"><code>log/syslog</code></a> package now provides better support
for OS-specific logging features.
</li>

<li>
The <a href="/pkg/math/big/"><code>math/big</code></a> package's
<a href="/pkg/math/big/#Int"><code>Int</code></a> type
now has methods
<a href="/pkg/math/big/#Int.MarshalJSON"><code>MarshalJSON</code></a>
and
<a href="/pkg/math/big/#Int.UnmarshalJSON"><code>UnmarshalJSON</code></a>
to convert to and from a JSON representation.
Also,
<a href="/pkg/math/big/#Int"><code>Int</code></a>
can now convert directly to and from a <code>uint64</code> using
<a href="/pkg/math/big/#Int.Uint64"><code>Uint64</code></a>
and
<a href="/pkg/math/big/#Int.SetUint64"><code>SetUint64</code></a>,
while
<a href="/pkg/math/big/#Rat"><code>Rat</code></a>
can do the same with <code>float64</code> using
<a href="/pkg/math/big/#Rat.Float64"><code>Float64</code></a>
and
<a href="/pkg/math/big/#Rat.SetFloat64"><code>SetFloat64</code></a>.
</li>

<li>
The <a href="/pkg/mime/multipart/"><code>mime/multipart</code></a> package
has a new method for its
<a href="/pkg/mime/multipart/#Writer"><code>Writer</code></a>,
<a href="/pkg/mime/multipart/#Writer.SetBoundary"><code>SetBoundary</code></a>,
to define the boundary separator used to package the output.
The <a href="/pkg/mime/multipart/#Reader"><code>Reader</code></a> also now
transparently decodes any <code>quoted-printable</code> parts and removes
the <code>Content-Transfer-Encoding</code> header when doing so.
</li>

<li>
The
<a href="/pkg/net/"><code>net</code></a> package's
<a href="/pkg/net/#ListenUnixgram"><code>ListenUnixgram</code></a>
function has changed return types: it now returns a
<a href="/pkg/net/#UnixConn"><code>UnixConn</code></a>
rather than a
<a href="/pkg/net/#UDPConn"><code>UDPConn</code></a>, which was
clearly a mistake in Go 1.0.
Since this API change fixes a bug, it is permitted by the Go 1 compatibility rules.
</li>

<li>
The <a href="/pkg/net/"><code>net</code></a> package includes a new type,
<a href="/pkg/net/#Dialer"><code>Dialer</code></a>, to supply options to
<a href="/pkg/net/#Dialer.Dial"><code>Dial</code></a>.
</li>

<li>
The <a href="/pkg/net/"><code>net</code></a> package adds support for
link-local IPv6 addresses with zone qualifiers, such as <code>fe80::1%lo0</code>.
The address structures <a href="/pkg/net/#IPAddr"><code>IPAddr</code></a>,
<a href="/pkg/net/#UDPAddr"><code>UDPAddr</code></a>, and
<a href="/pkg/net/#TCPAddr"><code>TCPAddr</code></a>
record the zone in a new field, and functions that expect string forms of these addresses, such as
<a href="/pkg/net/#Dial"><code>Dial</code></a>,
<a href="/pkg/net/#ResolveIPAddr"><code>ResolveIPAddr</code></a>,
<a href="/pkg/net/#ResolveUDPAddr"><code>ResolveUDPAddr</code></a>, and
<a href="/pkg/net/#ResolveTCPAddr"><code>ResolveTCPAddr</code></a>,
now accept the zone-qualified form.
</li>

<li>
The <a href="/pkg/net/"><code>net</code></a> package adds
<a href="/pkg/net/#LookupNS"><code>LookupNS</code></a> to its suite of resolving functions.
<code>LookupNS</code> returns the <a href="/pkg/net/#NS">NS records</a> for a host name.
</li>

<li>
The <a href="/pkg/net/"><code>net</code></a> package adds protocol-specific
packet reading and writing methods to
<a href="/pkg/net/#IPConn"><code>IPConn</code></a>
(<a href="/pkg/net/#IPConn.ReadMsgIP"><code>ReadMsgIP</code></a>
and <a href="/pkg/net/#IPConn.WriteMsgIP"><code>WriteMsgIP</code></a>) and
<a href="/pkg/net/#UDPConn"><code>UDPConn</code></a>
(<a href="/pkg/net/#UDPConn.ReadMsgUDP"><code>ReadMsgUDP</code></a> and
<a href="/pkg/net/#UDPConn.WriteMsgUDP"><code>WriteMsgUDP</code></a>).
These are specialized versions of <a href="/pkg/net/#PacketConn"><code>PacketConn</code></a>'s
<code>ReadFrom</code> and <code>WriteTo</code> methods that provide access to out-of-band data associated
with the packets.
 </li>

 <li>
The <a href="/pkg/net/"><code>net</code></a> package adds methods to
<a href="/pkg/net/#UnixConn"><code>UnixConn</code></a> to allow closing half of the connection
(<a href="/pkg/net/#UnixConn.CloseRead"><code>CloseRead</code></a> and
<a href="/pkg/net/#UnixConn.CloseWrite"><code>CloseWrite</code></a>),
matching the existing methods of <a href="/pkg/net/#TCPConn"><code>TCPConn</code></a>.
</li>

<li>
The <a href="/pkg/net/http/"><code>net/http</code></a> package includes several new additions.
<a href="/pkg/net/http/#ParseTime"><code>ParseTime</code></a> parses a time string, trying
several common HTTP time formats.
The <a href="/pkg/net/http/#Request.PostFormValue"><code>PostFormValue</code></a> method of
<a href="/pkg/net/http/#Request"><code>Request</code></a> is like
<a href="/pkg/net/http/#Request.FormValue"><code>FormValue</code></a> but ignores URL parameters.
The <a href="/pkg/net/http/#CloseNotifier"><code>CloseNotifier</code></a> interface provides a mechanism
for a server handler to discover when a client has disconnected.
The <code>ServeMux</code> type now has a
<a href="/pkg/net/http/#ServeMux.Handler"><code>Handler</code></a> method to access a path's
<code>Handler</code> without executing it.
The <code>Transport</code> can now cancel an in-flight request with
<a href="/pkg/net/http/#Transport.CancelRequest"><code>CancelRequest</code></a>.
Finally, the Transport is now more aggressive at closing TCP connections when
a <a href="/pkg/net/http/#Response"><code>Response.Body</code></a> is closed before
being fully consumed.
</li>

<li>
The <a href="/pkg/net/mail/"><code>net/mail</code></a> package has two new functions,
<a href="/pkg/net/mail/#ParseAddress"><code>ParseAddress</code></a> and
<a href="/pkg/net/mail/#ParseAddressList"><code>ParseAddressList</code></a>,
to parse RFC 5322-formatted mail addresses into
<a href="/pkg/net/mail/#Address"><code>Address</code></a> structures.
</li>

<li>
The <a href="/pkg/net/smtp/"><code>net/smtp</code></a> package's
<a href="/pkg/net/smtp/#Client"><code>Client</code></a> type has a new method,
<a href="/pkg/net/smtp/#Client.Hello"><code>Hello</code></a>,
which transmits a <code>HELO</code> or <code>EHLO</code> message to the server.
</li>

<li>
The <a href="/pkg/net/textproto/"><code>net/textproto</code></a> package
has two new functions,
<a href="/pkg/net/textproto/#TrimBytes"><code>TrimBytes</code></a> and
<a href="/pkg/net/textproto/#TrimString"><code>TrimString</code></a>,
which do ASCII-only trimming of leading and trailing spaces.
</li>

<li>
The new method <a href="/pkg/os/#FileMode.IsRegular"><code>os.FileMode.IsRegular</code></a> makes it easy to ask if a file is a plain file.
</li>

<li>
The <a href="/pkg/os/signal/"><code>os/signal</code></a> package has a new function,
<a href="/pkg/os/signal/#Stop"><code>Stop</code></a>, which stops the package delivering
any further signals to the channel.
</li>

<li>
The <a href="/pkg/regexp/"><code>regexp</code></a> package
now supports Unix-original leftmost-longest matches through the
<a href="/pkg/regexp/#Regexp.Longest"><code>Regexp.Longest</code></a>
method, while
<a href="/pkg/regexp/#Regexp.Split"><code>Regexp.Split</code></a> slices
strings into pieces based on separators defined by the regular expression.
</li>

<li>
The <a href="/pkg/runtime/debug/"><code>runtime/debug</code></a> package
has three new functions regarding memory usage.
The <a href="/pkg/runtime/debug/#FreeOSMemory"><code>FreeOSMemory</code></a>
function triggers a run of the garbage collector and then attempts to return unused
memory to the operating system;
the <a href="/pkg/runtime/debug/#ReadGCStats"><code>ReadGCStats</code></a>
function retrieves statistics about the collector; and
<a href="/pkg/runtime/debug/#SetGCPercent"><code>SetGCPercent</code></a>
provides a programmatic way to control how often the collector runs,
including disabling it altogether.
</li>

<li>
The <a href="/pkg/sort/"><code>sort</code></a> package has a new function,
<a href="/pkg/sort/#Reverse"><code>Reverse</code></a>.
Wrapping the argument of a call to
<a href="/pkg/sort/#Sort"><code>sort.Sort</code></a>
with a call to <code>Reverse</code> causes the sort order to be reversed.
</li>

<li>
The <a href="/pkg/strings/"><code>strings</code></a> package has two new functions,
<a href="/pkg/strings/#TrimPrefix"><code>TrimPrefix</code></a>
and
<a href="/pkg/strings/#TrimSuffix"><code>TrimSuffix</code></a>
with self-evident properties, and the new method
<a href="/pkg/strings/#Reader.WriteTo"><code>Reader.WriteTo</code></a> so the
<a href="/pkg/strings/#Reader"><code>Reader</code></a>
type now implements the
<a href="/pkg/io/#WriterTo"><code>io.WriterTo</code></a> interface.
</li>

<li>
The <a href="/pkg/syscall/"><code>syscall</code></a> package's
<a href="/pkg/syscall/#Fchflags"><code>Fchflags</code></a> function on various BSDs
(including Darwin) has changed signature.
It now takes an int as the first parameter instead of a string.
Since this API change fixes a bug, it is permitted by the Go 1 compatibility rules.
</li>
<li>
The <a href="/pkg/syscall/"><code>syscall</code></a> package also has received many updates
to make it more inclusive of constants and system calls for each supported operating system.
</li>

<li>
The <a href="/pkg/testing/"><code>testing</code></a> package now automates the generation of allocation
statistics in tests and benchmarks using the new
<a href="/pkg/testing/#AllocsPerRun"><code>AllocsPerRun</code></a> function. And the
<a href="/pkg/testing/#B.ReportAllocs"><code>ReportAllocs</code></a>
method on <a href="/pkg/testing/#B"><code>testing.B</code></a> will enable printing of
memory allocation statistics for the calling benchmark. It also introduces the
<a href="/pkg/testing/#BenchmarkResult.AllocsPerOp"><code>AllocsPerOp</code></a> method of
<a href="/pkg/testing/#BenchmarkResult"><code>BenchmarkResult</code></a>.
There is also a new
<a href="/pkg/testing/#Verbose"><code>Verbose</code></a> function to test the state of the <code>-v</code>
command-line flag,
and a new
<a href="/pkg/testing/#B.Skip"><code>Skip</code></a> method of
<a href="/pkg/testing/#B"><code>testing.B</code></a> and
<a href="/pkg/testing/#T"><code>testing.T</code></a>
to simplify skipping an inappropriate test.
</li>

<li>
In the <a href="/pkg/text/template/"><code>text/template</code></a>
and
<a href="/pkg/html/template/"><code>html/template</code></a> packages,
templates can now use parentheses to group the elements of pipelines, simplifying the construction of complex pipelines.
Also, as part of the new parser, the
<a href="/pkg/text/template/parse/#Node"><code>Node</code></a> interface got two new methods to provide
better error reporting.
Although this violates the Go 1 compatibility rules,
no existing code should be affected because this interface is explicitly intended only to be used
by the
<a href="/pkg/text/template/"><code>text/template</code></a>
and
<a href="/pkg/html/template/"><code>html/template</code></a>
packages and there are safeguards to guarantee that.
</li>

<li>
The implementation of the <a href="/pkg/unicode/"><code>unicode</code></a> package has been updated to Unicode version 6.2.0.
</li>

<li>
In the <a href="/pkg/unicode/utf8/"><code>unicode/utf8</code></a> package,
the new function <a href="/pkg/unicode/utf8/#ValidRune"><code>ValidRune</code></a> reports whether the rune is a valid Unicode code point.
To be valid, a rune must be in range and not be a surrogate half.
</li>
</ul>