effective_go.html 95.9 KB
Newer Older
1
<!-- Effective Go -->
2 3 4 5 6
<!--
  DO NOT EDIT: created by
    tmpltohtml effective_go.tmpl
-->

Rob Pike's avatar
Rob Pike committed
7

Russ Cox's avatar
Russ Cox committed
8 9
<h2 id="introduction">Introduction</h2>

Rob Pike's avatar
Rob Pike committed
10
<p>
Rob Pike's avatar
Rob Pike committed
11 12 13
Go is a new language.  Although it borrows ideas from
existing languages,
it has unusual properties that make effective Go programs
Russ Cox's avatar
Russ Cox committed
14
different in character from programs written in its relatives.
15
A straightforward translation of a C++ or Java program into Go
Rob Pike's avatar
Rob Pike committed
16
is unlikely to produce a satisfactory result&mdash;Java programs
17 18 19 20 21 22
are written in Java, not Go.
On the other hand, thinking about the problem from a Go
perspective could produce a successful but quite different
program.
In other words,
to write Go well, it's important to understand its properties
Rob Pike's avatar
Rob Pike committed
23
and idioms.
24 25 26 27
It's also important to know the established conventions for
programming in Go, such as naming, formatting, program
construction, and so on, so that programs you write
will be easy for other Go programmers to understand.
Rob Pike's avatar
Rob Pike committed
28 29
</p>

Russ Cox's avatar
Russ Cox committed
30
<p>
31
This document gives tips for writing clear, idiomatic Go code.
Russ Cox's avatar
Russ Cox committed
32 33
It augments the <a href="go_spec.html">language specification</a>
and the <a href="go_tutorial.html">tutorial</a>, both of which you
Rob Pike's avatar
Rob Pike committed
34
should read first.
Russ Cox's avatar
Russ Cox committed
35 36
</p>

Rob Pike's avatar
Rob Pike committed
37
<h3 id="examples">Examples</h3>
Russ Cox's avatar
Russ Cox committed
38 39

<p>
Rob Pike's avatar
Rob Pike committed
40
The <a href="/src/pkg/">Go package sources</a>
Russ Cox's avatar
Russ Cox committed
41 42
are intended to serve not
only as the core library but also as examples of how to
43 44
use the language.
If you have a question about how to approach a problem or how something
Russ Cox's avatar
Russ Cox committed
45
might be implemented, they can provide answers, ideas and
46
background.
Russ Cox's avatar
Russ Cox committed
47 48 49 50 51 52 53 54
</p>


<h2 id="formatting">Formatting</h2>

<p>
Formatting issues are the most contentious
but the least consequential.
55 56 57 58 59 60
People can adapt to different formatting styles
but it's better if they don't have to, and
less time is devoted to the topic
if everyone adheres to the same style.
The problem is how to approach this Utopia without a long
prescriptive style guide.
Russ Cox's avatar
Russ Cox committed
61 62
</p>

63
<p>
Rob Pike's avatar
Rob Pike committed
64
With Go we take an unusual
65 66
approach and let the machine
take care of most formatting issues.
67
The <code>gofmt</code> tool reads a Go program
68 69 70 71 72
and emits the source in a standard style of indentation
and vertical alignment, retaining and if necessary
reformatting comments.
If you want to know how to handle some new layout
situation, run <code>gofmt</code>; if the answer doesn't
73 74
seem right, rearrange your program (or file a bug about <code>gofmt</code>),
don't work around it.
75
</p>
Russ Cox's avatar
Russ Cox committed
76 77

<p>
78 79 80 81
As an example, there's no need to spend time lining up
the comments on the fields of a structure.
<code>Gofmt</code> will do that for you.  Given the
declaration
Rob Pike's avatar
Rob Pike committed
82 83
</p>

84 85
<pre>
type T struct {
86 87
    name string // name of the object
    value int // its value
88 89
}
</pre>
Rob Pike's avatar
Rob Pike committed
90 91

<p>
Russ Cox's avatar
Russ Cox committed
92
<code>gofmt</code> will line up the columns:
Russ Cox's avatar
Russ Cox committed
93 94
</p>

95 96
<pre>
type T struct {
97 98
    name    string // name of the object
    value   int    // its value
99 100
}
</pre>
Russ Cox's avatar
Russ Cox committed
101 102

<p>
103
All Go code in the standard packages has been formatted with <code>gofmt</code>.
Russ Cox's avatar
Russ Cox committed
104 105 106 107
</p>


<p>
108
Some formatting details remain.  Very briefly,
Russ Cox's avatar
Russ Cox committed
109 110
</p>

111
<dl>
112 113 114 115 116 117 118 119 120 121 122 123
    <dt>Indentation</dt>
    <dd>We use tabs for indentation and <code>gofmt</code> emits them by default.
    Use spaces only if you must.
    </dd>
    <dt>Line length</dt>
    <dd>
    Go has no line length limit.  Don't worry about overflowing a punched card.
    If a line feels too long, wrap it and indent with an extra tab.
    </dd>
    <dt>Parentheses</dt>
    <dd>
    Go needs fewer parentheses: control structures (<code>if</code>,
124
    <code>for</code>, <code>switch</code>) do not have parentheses in
125 126
    their syntax.
    Also, the operator precedence hierarchy is shorter and clearer, so
127 128 129
<pre>
x&lt;&lt;8 + y&lt;&lt;16
</pre>
130 131
    means what the spacing implies.
    </dd>
132
</dl>
Russ Cox's avatar
Russ Cox committed
133

Rob Pike's avatar
Rob Pike committed
134
<h2 id="commentary">Commentary</h2>
Russ Cox's avatar
Russ Cox committed
135 136

<p>
137
Go provides C-style <code>/* */</code> block comments
Russ Cox's avatar
Russ Cox committed
138
and C++-style <code>//</code> line comments.
Rob Pike's avatar
Rob Pike committed
139 140 141
Line comments are the norm;
block comments appear mostly as package comments and
are also useful to disable large swaths of code.
Russ Cox's avatar
Russ Cox committed
142 143
</p>

Rob Pike's avatar
Rob Pike committed
144 145 146 147 148 149 150 151 152
<p>
The program—and web server—<code>godoc</code> processes
Go source files to extract documentation about the contents of the
package.
Comments that appear before top-level declarations, with no intervening newlines,
are extracted along with the declaration to serve as explanatory text for the item.
The nature and style of these comments determines the
quality of the documentation <code>godoc</code> produces.
</p>
Rob Pike's avatar
Rob Pike committed
153 154

<p>
Rob Pike's avatar
Rob Pike committed
155
Every package should have a <i>package comment</i>, a block
Rob Pike's avatar
Rob Pike committed
156
comment preceding the package clause.
Rob Pike's avatar
Rob Pike committed
157 158 159
For multi-file packages, the package comment only needs to be
present in one file, and any one will do.
The package comment should introduce the package and
Rob Pike's avatar
Rob Pike committed
160
provide information relevant to the package as a whole.
Rob Pike's avatar
Rob Pike committed
161 162
It will appear first on the <code>godoc</code> page and
should set up the detailed documentation that follows.
Rob Pike's avatar
Rob Pike committed
163 164 165 166
</p>

<pre>
/*
167
    Package regexp implements a simple library for
168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184
    regular expressions.

    The syntax of the regular expressions accepted is:

    regexp:
        concatenation { '|' concatenation }
    concatenation:
        { closure }
    closure:
        term [ '*' | '+' | '?' ]
    term:
        '^'
        '$'
        '.'
        character
        '[' [ '^' ] character-ranges ']'
        '(' regexp ')'
Rob Pike's avatar
Rob Pike committed
185 186 187 188 189
*/
package regexp
</pre>

<p>
Rob Pike's avatar
Rob Pike committed
190
If the package is simple, the package comment can be brief.
Rob Pike's avatar
Rob Pike committed
191 192 193
</p>

<pre>
194
// Package path implements utility routines for
Rob Pike's avatar
Rob Pike committed
195 196 197
// manipulating slash-separated filename paths.
</pre>

Russ Cox's avatar
Russ Cox committed
198
<p>
Rob Pike's avatar
Rob Pike committed
199 200
Comments do not need extra formatting such as banners of stars.
The generated output may not even be presented in a fixed-width font, so don't depend
201
on spacing for alignment&mdash;<code>godoc</code>, like <code>gofmt</code>,
Rob Pike's avatar
Rob Pike committed
202
takes care of that.
203
The comments are uninterpreted plain text, so HTML and other
Rob Pike's avatar
Rob Pike committed
204 205
annotations such as <code>_this_</code> will reproduce <i>verbatim</i> and should
not be used.
206 207 208 209
Depending on the context, <code>godoc</code> might not even
reformat comments, so make sure they look good straight up:
use correct spelling, punctuation, and sentence structure,
fold long lines, and so on.
Russ Cox's avatar
Russ Cox committed
210 211 212
</p>

<p>
Rob Pike's avatar
Rob Pike committed
213 214
Inside a package, any comment immediately preceding a top-level declaration
serves as a <i>doc comment</i> for that declaration.
Russ Cox's avatar
Russ Cox committed
215
Every exported (capitalized) name in a program should
Rob Pike's avatar
Rob Pike committed
216
have a doc comment.
Russ Cox's avatar
Russ Cox committed
217 218 219
</p>

<p>
220
Doc comments work best as complete sentences, which allow
Rob Pike's avatar
Rob Pike committed
221
a wide variety of automated presentations.
Russ Cox's avatar
Russ Cox committed
222
The first sentence should be a one-sentence summary that
223
starts with the name being declared.
Russ Cox's avatar
Russ Cox committed
224 225 226
</p>

<pre>
Rob Pike's avatar
Rob Pike committed
227 228
// Compile parses a regular expression and returns, if successful, a Regexp
// object that can be used to match against text.
229
func Compile(str string) (regexp *Regexp, err error) {
Russ Cox's avatar
Russ Cox committed
230 231
</pre>

Rob Pike's avatar
Rob Pike committed
232 233
<p>
Go's declaration syntax allows grouping of declarations.
Rob Pike's avatar
Rob Pike committed
234 235
A single doc comment can introduce a group of related constants or variables.
Since the whole declaration is presented, such a comment can often be perfunctory.
Rob Pike's avatar
Rob Pike committed
236 237 238
</p>

<pre>
Rob Pike's avatar
Rob Pike committed
239 240
// Error codes returned by failures to parse an expression.
var (
241 242 243
    ErrInternal      = errors.New("regexp: internal error")
    ErrUnmatchedLpar = errors.New("regexp: unmatched '('")
    ErrUnmatchedRpar = errors.New("regexp: unmatched ')'")
244
    ...
Rob Pike's avatar
Rob Pike committed
245 246 247 248
)
</pre>

<p>
Rob Pike's avatar
Rob Pike committed
249
Even for private names, grouping can also indicate relationships between items,
Russ Cox's avatar
Russ Cox committed
250
such as the fact that a set of variables is protected by a mutex.
Rob Pike's avatar
Rob Pike committed
251 252 253 254
</p>

<pre>
var (
255 256 257
    countLock   sync.Mutex
    inputCount  uint32
    outputCount uint32
258
    errorCount  uint32
Rob Pike's avatar
Rob Pike committed
259 260 261
)
</pre>

Russ Cox's avatar
Russ Cox committed
262 263
<h2 id="names">Names</h2>

Rob Pike's avatar
names  
Rob Pike committed
264 265 266 267
<p>
Names are as important in Go as in any other language.
In some cases they even have semantic effect: for instance,
the visibility of a name outside a package is determined by whether its
Rob Pike's avatar
Rob Pike committed
268
first character is upper case.
Rob Pike's avatar
names  
Rob Pike committed
269 270 271 272 273 274
It's therefore worth spending a little time talking about naming conventions
in Go programs.
</p>


<h3 id="package-names">Package names</h3>
Russ Cox's avatar
Russ Cox committed
275 276

<p>
Rob Pike's avatar
names  
Rob Pike committed
277 278
When a package is imported, the package name becomes an accessor for the
contents.  After
Russ Cox's avatar
Russ Cox committed
279 280
</p>

Rob Pike's avatar
names  
Rob Pike committed
281 282 283
<pre>
import "bytes"
</pre>
Russ Cox's avatar
Russ Cox committed
284 285

<p>
Rob Pike's avatar
names  
Rob Pike committed
286 287 288 289 290 291 292 293 294 295 296 297
the importing package can talk about <code>bytes.Buffer</code>.  It's
helpful if everyone using the package can use the same name to refer to
its contents, which implies that the package name should be good:
short, concise, evocative.  By convention, packages are given
lower case, single-word names; there should be no need for underscores
or mixedCaps.
Err on the side of brevity, since everyone using your
package will be typing that name.
And don't worry about collisions <i>a priori</i>.
The package name is only the default name for imports; it need not be unique
across all source code, and in the rare case of a collision the
importing package can choose a different name to use locally.
Rob Pike's avatar
Rob Pike committed
298
In any case, confusion is rare because the file name in the import
Ian Lance Taylor's avatar
Ian Lance Taylor committed
299
determines just which package is being used.
Rob Pike's avatar
names  
Rob Pike committed
300 301 302 303 304
</p>

<p>
Another convention is that the package name is the base name of
its source directory;
305 306 307
the package in <code>src/pkg/encoding/base64</code>
is imported as <code>"encoding/base64"</code> but has name <code>base64</code>,
not <code>encoding_base64</code> and not <code>encodingBase64</code>.
Russ Cox's avatar
Russ Cox committed
308 309 310
</p>

<p>
Rob Pike's avatar
names  
Rob Pike committed
311 312
The importer of a package will use the name to refer to its contents
(the <code>import .</code> notation is intended mostly for tests and other
313 314
unusual situations and should be avoided unless necessary),
so exported names in the package can use that fact
Rob Pike's avatar
names  
Rob Pike committed
315 316 317 318 319 320 321
to avoid stutter.
For instance, the buffered reader type in the <code>bufio</code> package is called <code>Reader</code>,
not <code>BufReader</code>, because users see it as <code>bufio.Reader</code>,
which is a clear, concise name.
Moreover,
because imported entities are always addressed with their package name, <code>bufio.Reader</code>
does not conflict with <code>io.Reader</code>.
322
Similarly, the function to make new instances of <code>ring.Ring</code>&mdash;which
Russ Cox's avatar
Russ Cox committed
323
is the definition of a <em>constructor</em> in Go&mdash;would
324 325
normally be called <code>NewRing</code>, but since
<code>Ring</code> is the only type exported by the package, and since the
326 327
package is called <code>ring</code>, it's called just <code>New</code>,
which clients of the package see as <code>ring.New</code>.
Rob Pike's avatar
names  
Rob Pike committed
328
Use the package structure to help you choose good names.
Russ Cox's avatar
Russ Cox committed
329 330 331
</p>

<p>
Rob Pike's avatar
names  
Rob Pike committed
332 333 334 335 336 337 338
Another short example is <code>once.Do</code>;
<code>once.Do(setup)</code> reads well and would not be improved by
writing <code>once.DoOrWaitUntilDone(setup)</code>.
Long names don't automatically make things more readable.
If the name represents something intricate or subtle, it's usually better
to write a helpful doc comment than to attempt to put all the information
into the name.
Russ Cox's avatar
Russ Cox committed
339 340
</p>

341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357
<h3 id="Getters">Getters</h3>

<p>
Go doesn't provide automatic support for getters and setters.
There's nothing wrong with providing getters and setters yourself,
and it's often appropriate to do so, but it's neither idiomatic nor necessary
to put <code>Get</code> into the getter's name.  If you have a field called
<code>owner</code> (lower case, unexported), the getter method should be
called <code>Owner</code> (upper case, exported), not <code>GetOwner</code>.
The use of upper-case names for export provides the hook to discriminate
the field from the method.
A setter function, if needed, will likely be called <code>SetOwner</code>.
Both names read well in practice:
</p>
<pre>
owner := obj.Owner()
if owner != user {
358
    obj.SetOwner(user)
359 360 361
}
</pre>

Rob Pike's avatar
names  
Rob Pike committed
362
<h3 id="interface-names">Interface names</h3>
Russ Cox's avatar
Russ Cox committed
363 364

<p>
Rob Pike's avatar
names  
Rob Pike committed
365
By convention, one-method interfaces are named by
Russ Cox's avatar
Russ Cox committed
366
the method name plus the -er suffix: <code>Reader</code>,
Rob Pike's avatar
names  
Rob Pike committed
367
<code>Writer</code>, <code>Formatter</code> etc.
Russ Cox's avatar
Russ Cox committed
368 369 370
</p>

<p>
Rob Pike's avatar
names  
Rob Pike committed
371 372 373 374
There are a number of such names and it's productive to honor them and the function
names they capture.
<code>Read</code>, <code>Write</code>, <code>Close</code>, <code>Flush</code>,
<code>String</code> and so on have
Russ Cox's avatar
Russ Cox committed
375 376 377 378 379
canonical signatures and meanings.  To avoid confusion,
don't give your method one of those names unless it
has the same signature and meaning.
Conversely, if your type implements a method with the
same meaning as a method on a well-known type,
Rob Pike's avatar
names  
Rob Pike committed
380 381
give it the same name and signature;
call your string-converter method <code>String</code> not <code>ToString</code>.
Russ Cox's avatar
Russ Cox committed
382 383
</p>

Rob Pike's avatar
names  
Rob Pike committed
384 385
<h3 id="mixed-caps">MixedCaps</h3>

Russ Cox's avatar
Russ Cox committed
386
<p>
Rob Pike's avatar
Rob Pike committed
387
Finally, the convention in Go is to use <code>MixedCaps</code>
Rob Pike's avatar
names  
Rob Pike committed
388 389
or <code>mixedCaps</code> rather than underscores to write
multiword names.
Russ Cox's avatar
Russ Cox committed
390 391
</p>

Rob Pike's avatar
Rob Pike committed
392
<h2 id="semicolons">Semicolons</h2>
Rob Pike's avatar
names  
Rob Pike committed
393

Rob Pike's avatar
Rob Pike committed
394
<p>
395 396 397 398
Like C, Go's formal grammar uses semicolons to terminate statements;
unlike C, those semicolons do not appear in the source.
Instead the lexer uses a simple rule to insert semicolons automatically
as it scans, so the input text is mostly free of them.
Rob Pike's avatar
Rob Pike committed
399
</p>
Russ Cox's avatar
Russ Cox committed
400

401 402 403 404 405 406 407 408 409 410 411 412
<p>
The rule is this. If the last token before a newline is an identifier
(which includes words like <code>int</code> and <code>float64</code>),
a basic literal such as a number or string constant, or one of the
tokens
</p>
<pre>
break continue fallthrough return ++ -- ) }
</pre>
<p>
the lexer always inserts a semicolon after the token.
This could be summarized as, &ldquo;if the newline comes
413
after a token that could end a statement, insert a semicolon&rdquo;.
414 415 416 417 418 419
</p>

<p>
A semicolon can also be omitted immediately before a closing brace,
so a statement such as
</p>
Rob Pike's avatar
Rob Pike committed
420 421 422
<pre>
    go func() { for { dst &lt;- &lt;-src } }()
</pre>
423 424 425 426 427 428 429
<p>
needs no semicolons.
Idiomatic Go programs have semicolons only in places such as
<code>for</code> loop clauses, to separate the initializer, condition, and
continuation elements.  They are also necessary to separate multiple
statements on a line, should you write code that way.
</p>
Russ Cox's avatar
Russ Cox committed
430 431

<p>
432 433 434 435 436
One caveat. You should never put the opening brace of a
control structure (<code>if</code>, <code>for</code>, <code>switch</code>,
or <code>select</code>) on the next line.  If you do, a semicolon
will be inserted before the brace, which could cause unwanted
effects.  Write them like this
Russ Cox's avatar
Russ Cox committed
437 438
</p>

Rob Pike's avatar
Rob Pike committed
439
<pre>
440
if i &lt; f() {
441
    g()
Rob Pike's avatar
Rob Pike committed
442
}
443
</pre>
Rob Pike's avatar
Rob Pike committed
444
<p>
445
not like this
Rob Pike's avatar
Rob Pike committed
446
</p>
447
<pre>
448
if i &lt; f()  // wrong!
449 450 451 452 453
{           // wrong!
    g()
}
</pre>

Rob Pike's avatar
Rob Pike committed
454 455 456 457

<h2 id="control-structures">Control structures</h2>

<p>
458
The control structures of Go are related to those of C but differ
Rob Pike's avatar
Rob Pike committed
459 460 461 462 463 464 465 466 467
in important ways.
There is no <code>do</code> or <code>while</code> loop, only a
slightly generalized
<code>for</code>;
<code>switch</code> is more flexible;
<code>if</code> and <code>switch</code> accept an optional
initialization statement like that of <code>for</code>;
and there are new control structures including a type switch and a
multiway communications multiplexer, <code>select</code>.
Rob Pike's avatar
Rob Pike committed
468
The syntax is also slightly different:
469
there are no parentheses
Rob Pike's avatar
Rob Pike committed
470 471 472 473 474 475 476 477
and the bodies must always be brace-delimited.
</p>

<h3 id="if">If</h3>

<p>
In Go a simple <code>if</code> looks like this:
</p>
478
<pre>
479
if x &gt; 0 {
Rob Pike's avatar
Rob Pike committed
480 481
    return y
}
Rob Pike's avatar
Rob Pike committed
482
</pre>
Russ Cox's avatar
Russ Cox committed
483

Rob Pike's avatar
Rob Pike committed
484 485 486 487 488 489 490 491 492
<p>
Mandatory braces encourage writing simple <code>if</code> statements
on multiple lines.  It's good style to do so anyway,
especially when the body contains a control statement such as a
<code>return</code> or <code>break</code>.
</p>

<p>
Since <code>if</code> and <code>switch</code> accept an initialization
493
statement, it's common to see one used to set up a local variable.
Rob Pike's avatar
Rob Pike committed
494
</p>
Russ Cox's avatar
Russ Cox committed
495 496

<pre>
Rob Pike's avatar
Rob Pike committed
497
if err := file.Chmod(0664); err != nil {
498
    log.Print(err)
499
    return err
Rob Pike's avatar
Rob Pike committed
500
}
Russ Cox's avatar
Russ Cox committed
501 502
</pre>

Rob Pike's avatar
Rob Pike committed
503 504 505 506 507 508 509
<p id="else">
In the Go libraries, you'll find that
when an <code>if</code> statement doesn't flow into the next statement—that is,
the body ends in <code>break</code>, <code>continue</code>,
<code>goto</code>, or <code>return</code>—the unnecessary
<code>else</code> is omitted.
</p>
Russ Cox's avatar
Russ Cox committed
510

Rob Pike's avatar
Rob Pike committed
511
<pre>
512
f, err := os.Open(name)
Rob Pike's avatar
Rob Pike committed
513
if err != nil {
514
    return err
Rob Pike's avatar
Rob Pike committed
515
}
516
codeUsing(f)
Rob Pike's avatar
Rob Pike committed
517
</pre>
Russ Cox's avatar
Russ Cox committed
518 519

<p>
520 521
This is an example of a common situation where code must guard against a
sequence of error conditions.  The code reads well if the
Rob Pike's avatar
Rob Pike committed
522 523
successful flow of control runs down the page, eliminating error cases
as they arise.  Since error cases tend to end in <code>return</code>
524
statements, the resulting code needs no <code>else</code> statements.
Russ Cox's avatar
Russ Cox committed
525 526 527
</p>

<pre>
528
f, err := os.Open(name)
Russ Cox's avatar
Russ Cox committed
529
if err != nil {
530
    return err
Russ Cox's avatar
Russ Cox committed
531
}
532
d, err := f.Stat()
Rob Pike's avatar
Rob Pike committed
533
if err != nil {
Rob Pike's avatar
Rob Pike committed
534
    f.Close()
535
    return err
Rob Pike's avatar
Rob Pike committed
536
}
537
codeUsing(f, d)
Russ Cox's avatar
Russ Cox committed
538 539
</pre>

Rob Pike's avatar
Rob Pike committed
540

Rob Pike's avatar
Rob Pike committed
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
<h3 id="redeclaration">Redeclaration</h3>

<p>
An aside: The last example in the previous section demonstrates a detail of how the
<code>:=</code> short declaration form works.
The declaration that calls <code>os.Open</code> reads,
</p>

<pre>
f, err := os.Open(name)
</pre>

<p>
This statement declares two variables, <code>f</code> and <code>err</code>.
A few lines later, the call to <code>f.Stat</code> reads,
</p>

<pre>
d, err := f.Stat()
</pre>

<p>
which looks as if it declares <code>d</code> and <code>err</code>.
Notice, though, that <code>err</code> appears in both statements.
This duplication is legal: <code>err</code> is declared by the first statement,
but only <em>re-assigned</em> in the second.
This means that the call to <code>f.Stat</code> uses the existing
<code>err</code> variable declared above, and just gives it a new value.
</p>

<p>
In a <code>:=</code> declaration a variable <code>v</code> may appear even
if it has already been declared, provided:
</p>

<ul>
<li>this declaration is in the same scope as the existing declaration of <code>v</code>
(if <code>v</code> is already declared in an outer scope, the declaration will create a new variable),</li>
<li>the corresponding value in the initialization is assignable to <code>v</code>, and</li>
<li>there is at least one other variable in the declaration that is being declared anew.</li>
</ul>

<p>
This unusual property is pure pragmatism,
making it easy to use a single <code>err</code> value, for example,
in a long <code>if-else</code> chain.
You'll see it used often.
</p>

Rob Pike's avatar
Rob Pike committed
590 591 592
<h3 id="for">For</h3>

<p>
593
The Go <code>for</code> loop is similar to&mdash;but not the same as&mdash;C's.
Rob Pike's avatar
Rob Pike committed
594 595
It unifies <code>for</code>
and <code>while</code> and there is no <code>do-while</code>.
596
There are three forms, only one of which has semicolons.
Rob Pike's avatar
Rob Pike committed
597 598
</p>
<pre>
Rob Pike's avatar
Rob Pike committed
599
// Like a C for
Rob Pike's avatar
Rob Pike committed
600 601
for init; condition; post { }

Rob Pike's avatar
Rob Pike committed
602
// Like a C while
Rob Pike's avatar
Rob Pike committed
603 604 605 606 607 608 609
for condition { }

// Like a C for(;;)
for { }
</pre>

<p>
610
Short declarations make it easy to declare the index variable right in the loop.
Rob Pike's avatar
Rob Pike committed
611 612
</p>
<pre>
613
sum := 0
614
for i := 0; i &lt; 10; i++ {
Rob Pike's avatar
Rob Pike committed
615 616 617 618 619
    sum += i
}
</pre>

<p>
Rob Pike's avatar
Rob Pike committed
620 621
If you're looping over an array, slice, string, or map,
or reading from a channel, a <code>range</code> clause can
622
manage the loop.
Rob Pike's avatar
Rob Pike committed
623 624
</p>
<pre>
625 626
var m map[string]int
sum := 0
Rob Pike's avatar
Rob Pike committed
627
for _, value := range m {  // key is unused
Rob Pike's avatar
Rob Pike committed
628 629 630 631
    sum += value
}
</pre>

Rob Pike's avatar
Rob Pike committed
632
<p>
Rob Pike's avatar
Rob Pike committed
633
For strings, the <code>range</code> does more work for you, breaking out individual
634 635 636
Unicode characters by parsing the UTF-8.
Erroneous encodings consume one byte and produce the
replacement rune U+FFFD. The loop
Rob Pike's avatar
Rob Pike committed
637 638 639 640 641 642 643 644 645 646 647 648 649 650 651
</p>
<pre>
for pos, char := range "日本語" {
    fmt.Printf("character %c starts at byte position %d\n", char, pos)
}
</pre>
<p>
prints
</p>
<pre>
character 日 starts at byte position 0
character 本 starts at byte position 3
character 語 starts at byte position 6
</pre>

Rob Pike's avatar
Rob Pike committed
652
<p>
653 654 655
Finally, Go has no comma operator and <code>++</code> and <code>--</code>
are statements not expressions.
Thus if you want to run multiple variables in a <code>for</code>
656
you should use parallel assignment.
Rob Pike's avatar
Rob Pike committed
657 658 659
</p>
<pre>
// Reverse a
660
for i, j := 0, len(a)-1; i &lt; j; i, j = i+1, j-1 {
661
    a[i], a[j] = a[j], a[i]
Rob Pike's avatar
Rob Pike committed
662 663 664
}
</pre>

Russ Cox's avatar
Russ Cox committed
665 666 667
<h3 id="switch">Switch</h3>

<p>
Rob Pike's avatar
Rob Pike committed
668
Go's <code>switch</code> is more general than C's.
Rob Pike's avatar
Rob Pike committed
669 670 671 672
The expressions need not be constants or even integers,
the cases are evaluated top to bottom until a match is found,
and if the <code>switch</code> has no expression it switches on
<code>true</code>.
673
It's therefore possible&mdash;and idiomatic&mdash;to write an
Rob Pike's avatar
Rob Pike committed
674
<code>if</code>-<code>else</code>-<code>if</code>-<code>else</code>
675
chain as a <code>switch</code>.
Russ Cox's avatar
Russ Cox committed
676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691
</p>

<pre>
func unhex(c byte) byte {
    switch {
    case '0' &lt;= c &amp;&amp; c &lt;= '9':
        return c - '0'
    case 'a' &lt;= c &amp;&amp; c &lt;= 'f':
        return c - 'a' + 10
    case 'A' &lt;= c &amp;&amp; c &lt;= 'F':
        return c - 'A' + 10
    }
    return 0
}
</pre>

Rob Pike's avatar
Rob Pike committed
692 693
<p>
There is no automatic fall through, but cases can be presented
694
in comma-separated lists.
Russ Cox's avatar
Russ Cox committed
695 696 697
<pre>
func shouldEscape(c byte) bool {
    switch c {
Rob Pike's avatar
Rob Pike committed
698
    case ' ', '?', '&amp;', '=', '#', '+', '%':
Russ Cox's avatar
Russ Cox committed
699 700 701 702 703 704
        return true
    }
    return false
}
</pre>

Rob Pike's avatar
Rob Pike committed
705 706 707
<p>
Here's a comparison routine for byte arrays that uses two
<code>switch</code> statements:
Rob Pike's avatar
Rob Pike committed
708
<pre>
Rob Pike's avatar
Rob Pike committed
709 710
// Compare returns an integer comparing the two byte arrays
// lexicographically.
Rob Pike's avatar
Rob Pike committed
711
// The result will be 0 if a == b, -1 if a &lt; b, and +1 if a &gt; b
Rob Pike's avatar
Rob Pike committed
712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730
func Compare(a, b []byte) int {
    for i := 0; i &lt; len(a) &amp;&amp; i &lt; len(b); i++ {
        switch {
        case a[i] &gt; b[i]:
            return 1
        case a[i] &lt; b[i]:
            return -1
        }
    }
    switch {
    case len(a) &lt; len(b):
        return -1
    case len(a) &gt; len(b):
        return 1
    }
    return 0
}
</pre>

Rob Pike's avatar
Rob Pike committed
731 732 733 734 735 736 737 738 739 740
<p>
A switch can also be used to discover the dynamic type of an interface
variable.  Such a <em>type switch</em> uses the syntax of a type
assertion with the keyword <code>type</code> inside the parentheses.
If the switch declares a variable in the expression, the variable will
have the corresponding type in each clause.
</p>
<pre>
switch t := interfaceValue.(type) {
default:
741
    fmt.Printf("unexpected type %T", t)  // %T prints type
Rob Pike's avatar
Rob Pike committed
742
case bool:
743
    fmt.Printf("boolean %t\n", t)
Rob Pike's avatar
Rob Pike committed
744
case int:
745
    fmt.Printf("integer %d\n", t)
Rob Pike's avatar
Rob Pike committed
746
case *bool:
747
    fmt.Printf("pointer to boolean %t\n", *t)
Rob Pike's avatar
Rob Pike committed
748
case *int:
749
    fmt.Printf("pointer to integer %d\n", *t)
Rob Pike's avatar
Rob Pike committed
750 751 752
}
</pre>

Russ Cox's avatar
Russ Cox committed
753 754
<h2 id="functions">Functions</h2>

Rob Pike's avatar
Rob Pike committed
755 756 757
<h3 id="multiple-returns">Multiple return values</h3>

<p>
Ian Lance Taylor's avatar
Ian Lance Taylor committed
758
One of Go's unusual features is that functions and methods
759
can return multiple values.  This form can be used to
Rob Pike's avatar
Rob Pike committed
760
improve on a couple of clumsy idioms in C programs: in-band
Rob Pike's avatar
Rob Pike committed
761
error returns (such as <code>-1</code> for <code>EOF</code>)
Rob Pike's avatar
Rob Pike committed
762 763 764 765
and modifying an argument.
</p>

<p>
Russ Cox's avatar
Russ Cox committed
766
In C, a write error is signaled by a negative count with the
Rob Pike's avatar
Rob Pike committed
767 768
error code secreted away in a volatile location.
In Go, <code>Write</code>
Russ Cox's avatar
Russ Cox committed
769 770
can return a count <i>and</i> an error: &ldquo;Yes, you wrote some
bytes but not all of them because you filled the device&rdquo;.
Rob Pike's avatar
Rob Pike committed
771 772 773 774
The signature of <code>*File.Write</code> in package <code>os</code> is:
</p>

<pre>
775
func (file *File) Write(b []byte) (n int, err error)
Rob Pike's avatar
Rob Pike committed
776 777 778 779
</pre>

<p>
and as the documentation says, it returns the number of bytes
780
written and a non-nil <code>error</code> when <code>n</code>
Rob Pike's avatar
Rob Pike committed
781 782 783 784 785 786
<code>!=</code> <code>len(b)</code>.
This is a common style; see the section on error handling for more examples.
</p>

<p>
A similar approach obviates the need to pass a pointer to a return
Rob Pike's avatar
Rob Pike committed
787 788
value to simulate a reference parameter.
Here's a simple-minded function to
Rob Pike's avatar
Rob Pike committed
789 790 791 792 793 794
grab a number from a position in a byte array, returning the number
and the next position.
</p>

<pre>
func nextInt(b []byte, i int) (int, int) {
795
    for ; i &lt; len(b) &amp;&amp; !isDigit(b[i]); i++ {
796 797
    }
    x := 0
798
    for ; i &lt; len(b) &amp;&amp; isDigit(b[i]); i++ {
799 800 801
        x = x*10 + int(b[i])-'0'
    }
    return x, i
Rob Pike's avatar
Rob Pike committed
802 803 804 805 806 807 808 809
}
</pre>

<p>
You could use it to scan the numbers in an input array <code>a</code> like this:
</p>

<pre>
810
    for i := 0; i &lt; len(a); {
811 812 813
        x, i = nextInt(a, i)
        fmt.Println(x)
    }
Rob Pike's avatar
Rob Pike committed
814 815 816
</pre>

<h3 id="named-results">Named result parameters</h3>
Russ Cox's avatar
Russ Cox committed
817 818

<p>
Rob Pike's avatar
Rob Pike committed
819 820
The return or result "parameters" of a Go function can be given names and
used as regular variables, just like the incoming parameters.
Rob Pike's avatar
Rob Pike committed
821
When named, they are initialized to the zero values for their types when
Rob Pike's avatar
Rob Pike committed
822
the function begins; if the function executes a <code>return</code> statement
823
with no arguments, the current values of the result parameters are
Rob Pike's avatar
Rob Pike committed
824
used as the returned values.
Russ Cox's avatar
Russ Cox committed
825 826
</p>

Rob Pike's avatar
Rob Pike committed
827 828 829 830 831 832 833 834 835 836 837
<p>
The names are not mandatory but they can make code shorter and clearer:
they're documentation.
If we name the results of <code>nextInt</code> it becomes
obvious which returned <code>int</code>
is which.
</p>

<pre>
func nextInt(b []byte, pos int) (value, nextPos int) {
</pre>
Russ Cox's avatar
Russ Cox committed
838 839

<p>
Rob Pike's avatar
Rob Pike committed
840 841 842
Because named results are initialized and tied to an unadorned return, they can simplify
as well as clarify.  Here's a version
of <code>io.ReadFull</code> that uses them well:
Russ Cox's avatar
Russ Cox committed
843 844
</p>

Rob Pike's avatar
Rob Pike committed
845
<pre>
846
func ReadFull(r Reader, buf []byte) (n int, err error) {
847
    for len(buf) &gt; 0 &amp;&amp; err == nil {
848 849 850
        var nr int
        nr, err = r.Read(buf)
        n += nr
851
        buf = buf[nr:]
852 853
    }
    return
Rob Pike's avatar
Rob Pike committed
854 855 856
}
</pre>

857 858 859 860 861 862 863 864 865 866 867 868 869
<h3 id="defer">Defer</h3>

<p>
Go's <code>defer</code> statement schedules a function call (the
<i>deferred</i> function) to be run immediately before the function
executing the <code>defer</code> returns.  It's an unusual but
effective way to deal with situations such as resources that must be
released regardless of which path a function takes to return.  The
canonical examples are unlocking a mutex or closing a file.
</p>

<pre>
// Contents returns the file's contents as a string.
870
func Contents(filename string) (string, error) {
871
    f, err := os.Open(filename)
872 873 874 875 876 877 878 879 880
    if err != nil {
        return "", err
    }
    defer f.Close()  // f.Close will run when we're finished.

    var result []byte
    buf := make([]byte, 100)
    for {
        n, err := f.Read(buf[0:])
881
        result = append(result, buf[0:n]...) // append is discussed later.
882
        if err != nil {
883
            if err == io.EOF {
884 885 886 887 888 889 890 891 892 893
                break
            }
            return "", err  // f will be closed if we return here.
        }
    }
    return string(result), nil // f will be closed if we return here.
}
</pre>

<p>
894
Deferring a call to a function such as <code>Close</code> has two advantages.  First, it
895 896 897 898 899 900 901
guarantees that you will never forget to close the file, a mistake
that's easy to make if you later edit the function to add a new return
path.  Second, it means that the close sits near the open,
which is much clearer than placing it at the end of the function.
</p>

<p>
902
The arguments to the deferred function (which include the receiver if
903 904 905 906 907 908 909 910
the function is a method) are evaluated when the <i>defer</i>
executes, not when the <i>call</i> executes.  Besides avoiding worries
about variables changing values as the function executes, this means
that a single deferred call site can defer multiple function
executions.  Here's a silly example.
</p>

<pre>
911
for i := 0; i &lt; 5; i++ {
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
    defer fmt.Printf("%d ", i)
}
</pre>

<p>
Deferred functions are executed in LIFO order, so this code will cause
<code>4 3 2 1 0</code> to be printed when the function returns.  A
more plausible example is a simple way to trace function execution
through the program.  We could write a couple of simple tracing
routines like this:
</p>

<pre>
func trace(s string)   { fmt.Println("entering:", s) }
func untrace(s string) { fmt.Println("leaving:", s) }

// Use them like this:
func a() {
    trace("a")
    defer untrace("a")
    // do something....
}
</pre>

<p>
We can do better by exploiting the fact that arguments to deferred
functions are evaluated when the <code>defer</code> executes.  The
tracing routine can set up the argument to the untracing routine.
This example:
</p>

<pre>
func trace(s string) string {
    fmt.Println("entering:", s)
    return s
}

func un(s string) {
    fmt.Println("leaving:", s)
}

func a() {
    defer un(trace("a"))
    fmt.Println("in a")
}

func b() {
    defer un(trace("b"))
    fmt.Println("in b")
    a()
}

func main() {
    b()
}
</pre>

<p>
prints
</p>

<pre>
entering: b
in b
entering: a
in a
leaving: a
leaving: b
</pre>

<p>
For programmers accustomed to block-level resource management from
other languages, <code>defer</code> may seem peculiar, but its most
interesting and powerful applications come precisely from the fact
986 987 988
that it's not block-based but function-based.  In the section on
<code>panic</code> and <code>recover</code> we'll see another
example of its possibilities.
989 990
</p>

991
<h2 id="data">Data</h2>
Rob Pike's avatar
Rob Pike committed
992

993
<h3 id="allocation_new">Allocation with <code>new</code></h3>
Rob Pike's avatar
Rob Pike committed
994

995
<p>
996 997
Go has two allocation primitives, the built-in functions
<code>new</code> and <code>make</code>.
998 999
They do different things and apply to different types, which can be confusing,
but the rules are simple.
1000
Let's talk about <code>new</code> first.
1001 1002 1003 1004 1005
It's a built-in function that allocates memory, but unlike its namesakes
in some other languages it does not <em>initialize</em> the memory,
it only <em>zeroes</em> it.
That is,
<code>new(T)</code> allocates zeroed storage for a new item of type
1006 1007 1008 1009 1010 1011
<code>T</code> and returns its address, a value of type <code>*T</code>.
In Go terminology, it returns a pointer to a newly allocated zero value of type
<code>T</code>.
</p>

<p>
1012 1013 1014
Since the memory returned by <code>new</code> is zeroed, it's helpful to arrange
when designing your data structures that the
zero value of each type can be used without further initialization.  This means a user of
1015
the data structure can create one with <code>new</code> and get right to
1016 1017 1018 1019 1020 1021 1022 1023 1024 1025
work.
For example, the documentation for <code>bytes.Buffer</code> states that
"the zero value for <code>Buffer</code> is an empty buffer ready to use."
Similarly, <code>sync.Mutex</code> does not
have an explicit constructor or <code>Init</code> method.
Instead, the zero value for a <code>sync.Mutex</code>
is defined to be an unlocked mutex.
</p>

<p>
1026
The zero-value-is-useful property works transitively. Consider this type declaration.
1027 1028 1029 1030
</p>

<pre>
type SyncedBuffer struct {
1031 1032
    lock    sync.Mutex
    buffer  bytes.Buffer
1033 1034 1035 1036 1037
}
</pre>

<p>
Values of type <code>SyncedBuffer</code> are also ready to use immediately upon allocation
1038
or just declaration.  In the next snippet, both <code>p</code> and <code>v</code> will work
1039
correctly without further arrangement.
1040 1041 1042
</p>

<pre>
1043 1044
p := new(SyncedBuffer)  // type *SyncedBuffer
var v SyncedBuffer      // type  SyncedBuffer
1045 1046 1047 1048 1049 1050 1051
</pre>

<h3 id="composite_literals">Constructors and composite literals</h3>

<p>
Sometimes the zero value isn't good enough and an initializing
constructor is necessary, as in this example derived from
1052
package <code>os</code>.
1053 1054 1055 1056
</p>

<pre>
func NewFile(fd int, name string) *File {
1057 1058 1059 1060 1061 1062 1063 1064 1065
    if fd &lt; 0 {
        return nil
    }
    f := new(File)
    f.fd = fd
    f.name = name
    f.dirinfo = nil
    f.nepipe = 0
    return f
1066 1067 1068 1069
}
</pre>

<p>
1070
There's a lot of boiler plate in there.  We can simplify it
1071 1072 1073 1074 1075 1076 1077
using a <i>composite literal</i>, which is
an expression that creates a
new instance each time it is evaluated.
</p>

<pre>
func NewFile(fd int, name string) *File {
1078 1079 1080 1081 1082
    if fd &lt; 0 {
        return nil
    }
    f := File{fd, name, nil, 0}
    return &amp;f
1083 1084 1085 1086
}
</pre>

<p>
1087
Note that, unlike in C, it's perfectly OK to return the address of a local variable;
1088 1089
the storage associated with the variable survives after the function
returns.
Rob Pike's avatar
Rob Pike committed
1090 1091
In fact, taking the address of a composite literal
allocates a fresh instance each time it is evaluated,
1092
so we can combine these last two lines.
1093 1094 1095
</p>

<pre>
1096
    return &amp;File{fd, name, nil, 0}
1097 1098 1099 1100 1101 1102 1103 1104 1105 1106
</pre>

<p>
The fields of a composite literal are laid out in order and must all be present.
However, by labeling the elements explicitly as <i>field</i><code>:</code><i>value</i>
pairs, the initializers can appear in any
order, with the missing ones left as their respective zero values.  Thus we could say
</p>

<pre>
1107
    return &amp;File{fd: fd, name: name}
1108 1109 1110 1111
</pre>

<p>
As a limiting case, if a composite literal contains no fields at all, it creates
Russ Cox's avatar
Russ Cox committed
1112
a zero value for the type.  The expressions <code>new(File)</code> and <code>&amp;File{}</code> are equivalent.
1113 1114 1115 1116 1117
</p>

<p>
Composite literals can also be created for arrays, slices, and maps,
with the field labels being indices or map keys as appropriate.
Russ Cox's avatar
Russ Cox committed
1118
In these examples, the initializations work regardless of the values of <code>Enone</code>,
1119
<code>Eio</code>, and <code>Einval</code>, as long as they are distinct.
1120
</p>
Rob Pike's avatar
Rob Pike committed
1121

1122
<pre>
1123 1124 1125
a := [...]string   {Enone: "no error", Eio: "Eio", Einval: "invalid argument"}
s := []string      {Enone: "no error", Eio: "Eio", Einval: "invalid argument"}
m := map[int]string{Enone: "no error", Eio: "Eio", Einval: "invalid argument"}
1126 1127
</pre>

1128
<h3 id="allocation_make">Allocation with <code>make</code></h3>
Rob Pike's avatar
Rob Pike committed
1129 1130

<p>
1131 1132 1133
Back to allocation.
The built-in function <code>make(T, </code><i>args</i><code>)</code> serves
a purpose different from <code>new(T)</code>.
1134 1135 1136
It creates slices, maps, and channels only, and it returns an <em>initialized</em>
(not <em>zeroed</em>)
value of type <code>T</code> (not <code>*T</code>).
1137 1138 1139 1140 1141
The reason for the distinction
is that these three types are, under the covers, references to data structures that
must be initialized before use.
A slice, for example, is a three-item descriptor
containing a pointer to the data (inside an array), the length, and the
1142
capacity, and until those items are initialized, the slice is <code>nil</code>.
1143
For slices, maps, and channels,
1144 1145 1146
<code>make</code> initializes the internal data structure and prepares
the value for use.
For instance,
Rob Pike's avatar
Rob Pike committed
1147 1148 1149
</p>

<pre>
1150
make([]int, 10, 100)
Rob Pike's avatar
Rob Pike committed
1151 1152
</pre>

1153 1154 1155 1156 1157 1158 1159 1160 1161 1162
<p>
allocates an array of 100 ints and then creates a slice
structure with length 10 and a capacity of 100 pointing at the first
10 elements of the array.
(When making a slice, the capacity can be omitted; see the section on slices
for more information.)
In contrast, <code>new([]int)</code> returns a pointer to a newly allocated, zeroed slice
structure, that is, a pointer to a <code>nil</code> slice value.

<p>
1163 1164
These examples illustrate the difference between <code>new</code> and
<code>make</code>.
1165 1166 1167
</p>

<pre>
1168
var p *[]int = new([]int)       // allocates slice structure; *p == nil; rarely useful
1169
var v  []int = make([]int, 100) // the slice v now refers to a new array of 100 ints
1170 1171

// Unnecessarily complex:
1172 1173
var p *[]int = new([]int)
*p = make([]int, 100, 100)
1174 1175

// Idiomatic:
1176
v := make([]int, 100)
1177 1178 1179
</pre>

<p>
1180
Remember that <code>make</code> applies only to maps, slices and channels
Russ Cox's avatar
Russ Cox committed
1181
and does not return a pointer.
1182
To obtain an explicit pointer allocate with <code>new</code>.
1183 1184 1185 1186 1187 1188
</p>

<h3 id="arrays">Arrays</h3>

<p>
Arrays are useful when planning the detailed layout of memory and sometimes
Russ Cox's avatar
Russ Cox committed
1189
can help avoid allocation, but primarily
1190 1191 1192 1193 1194 1195
they are a building block for slices, the subject of the next section.
To lay the foundation for that topic, here are a few words about arrays.
</p>

<p>
There are major differences between the ways arrays work in Go and C.
1196
In Go,
1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212
</p>
<ul>
<li>
Arrays are values. Assigning one array to another copies all the elements.
</li>
<li>
In particular, if you pass an array to a function, it
will receive a <i>copy</i> of the array, not a pointer to it.
<li>
The size of an array is part of its type.  The types <code>[10]int</code>
and <code>[20]int</code> are distinct.
</li>
</ul>

<p>
The value property can be useful but also expensive; if you want C-like behavior and efficiency,
1213
you can pass a pointer to the array.
1214 1215
</p>

Rob Pike's avatar
Rob Pike committed
1216
<pre>
1217
func Sum(a *[3]float64) (sum float64) {
1218 1219 1220 1221
    for _, v := range *a {
        sum += v
    }
    return
1222 1223
}

1224
array := [...]float64{7.0, 8.5, 9.1}
1225
x := Sum(&amp;array)  // Note the explicit address-of operator
Rob Pike's avatar
Rob Pike committed
1226 1227
</pre>

1228 1229 1230 1231 1232 1233 1234
<p>
But even this style isn't idiomatic Go.  Slices are.
</p>

<h3 id="slices">Slices</h3>

<p>
Rob Pike's avatar
Rob Pike committed
1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245
Slices wrap arrays to give a more general, powerful, and convenient
interface to sequences of data.  Except for items with explicit
dimension such as transformation matrices, most array programming in
Go is done with slices rather than simple arrays.
</p>
<p>
Slices are <i>reference types</i>, which means that if you assign one
slice to another, both refer to the same underlying array.  For
instance, if a function takes a slice argument, changes it makes to
the elements of the slice will be visible to the caller, analogous to
passing a pointer to the underlying array.  A <code>Read</code>
Russ Cox's avatar
Russ Cox committed
1246 1247
function can therefore accept a slice argument rather than a pointer
and a count; the length within the slice sets an upper
Rob Pike's avatar
Rob Pike committed
1248 1249 1250 1251 1252
limit of how much data to read.  Here is the signature of the
<code>Read</code> method of the <code>File</code> type in package
<code>os</code>:
</p>
<pre>
1253
func (file *File) Read(buf []byte) (n int, err error)
Rob Pike's avatar
Rob Pike committed
1254 1255 1256 1257
</pre>
<p>
The method returns the number of bytes read and an error value, if
any.  To read into the first 32 bytes of a larger buffer
1258
<code>b</code>, <i>slice</i> (here used as a verb) the buffer.
Rob Pike's avatar
Rob Pike committed
1259 1260
</p>
<pre>
1261
    n, err := f.Read(buf[0:32])
Rob Pike's avatar
Rob Pike committed
1262 1263 1264
</pre>
<p>
Such slicing is common and efficient.  In fact, leaving efficiency aside for
1265
the moment, this snippet would also read the first 32 bytes of the buffer.
Rob Pike's avatar
Rob Pike committed
1266 1267
</p>
<pre>
1268
    var n int
1269
    var err error
1270
    for i := 0; i &lt; 32; i++ {
1271 1272 1273 1274 1275 1276 1277
        nbytes, e := f.Read(buf[i:i+1])  // Read one byte.
        if nbytes == 0 || e != nil {
            err = e
            break
        }
        n += nbytes
    }
Rob Pike's avatar
Rob Pike committed
1278 1279 1280
</pre>
<p>
The length of a slice may be changed as long as it still fits within
1281
the limits of the underlying array; just assign it to a slice of
Rob Pike's avatar
Rob Pike committed
1282 1283 1284 1285 1286 1287 1288 1289 1290 1291
itself.  The <i>capacity</i> of a slice, accessible by the built-in
function <code>cap</code>, reports the maximum length the slice may
assume.  Here is a function to append data to a slice.  If the data
exceeds the capacity, the slice is reallocated.  The
resulting slice is returned.  The function uses the fact that
<code>len</code> and <code>cap</code> are legal when applied to the
<code>nil</code> slice, and return 0.
</p>
<pre>
func Append(slice, data[]byte) []byte {
1292
    l := len(slice)
1293
    if l + len(data) &gt; cap(slice) {  // reallocate
1294 1295
        // Allocate double what's needed, for future growth.
        newSlice := make([]byte, (l+len(data))*2)
1296 1297
        // The copy function is predeclared and works for any slice type.
        copy(newSlice, slice)
1298 1299 1300 1301 1302 1303 1304
        slice = newSlice
    }
    slice = slice[0:l+len(data)]
    for i, c := range data {
        slice[l+i] = c
    }
    return slice
Rob Pike's avatar
Rob Pike committed
1305 1306 1307 1308 1309 1310
}
</pre>
<p>
We must return the slice afterwards because, although <code>Append</code>
can modify the elements of <code>slice</code>, the slice itself (the run-time data
structure holding the pointer, length, and capacity) is passed by value.
1311 1312 1313 1314 1315
<p>
The idea of appending to a slice is so useful it's captured by the
<code>append</code> built-in function.  To understand that function's
design, though, we need a little more information, so we'll return
to it later.
1316 1317 1318 1319
</p>


<h3 id="maps">Maps</h3>
Rob Pike's avatar
Rob Pike committed
1320 1321 1322 1323

<p>
Maps are a convenient and powerful built-in data structure to associate
values of different types.
Russ Cox's avatar
Russ Cox committed
1324 1325
The key can be of any type for which the equality operator is defined,
such as integers,
1326 1327
floating point and complex numbers,
strings, pointers, and interfaces (as long as the dynamic type
Russ Cox's avatar
Russ Cox committed
1328 1329
supports equality).  Structs, arrays and slices cannot be used as map keys,
because equality is not defined on those types.
Rob Pike's avatar
Rob Pike committed
1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340
Like slices, maps are a reference type. If you pass a map to a function
that changes the contents of the map, the changes will be visible
in the caller.
</p>
<p>
Maps can be constructed using the usual composite literal syntax
with colon-separated key-value pairs,
so it's easy to build them during initialization.
</p>
<pre>
var timeZone = map[string] int {
1341 1342 1343 1344 1345
    "UTC":  0*60*60,
    "EST": -5*60*60,
    "CST": -6*60*60,
    "MST": -7*60*60,
    "PST": -8*60*60,
Rob Pike's avatar
Rob Pike committed
1346 1347 1348 1349 1350
}
</pre>
<p>
Assigning and fetching map values looks syntactically just like
doing the same for arrays except that the index doesn't need to
1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361
be an integer.
</p>
<pre>
offset := timeZone["EST"]
</pre>
<p>
An attempt to fetch a map value with a key that
is not present in the map will return the zero value for the type
of the entries
in the map.  For instance, if the map contains integers, looking
up a non-existent key will return <code>0</code>.
1362 1363 1364
A set can be implemented as a map with value type <code>bool</code>.
Set the map entry to <code>true</code> to put the value in the set, and then
test it by simple indexing.
1365
</p>
1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376
<pre>
attended := map[string] bool {
    "Ann": true,
    "Joe": true,
    ...
}

if attended[person] { // will be false if person is not in the map
    fmt.Println(person, "was at the meeting")
}
</pre>
1377 1378 1379 1380 1381
<p>
Sometimes you need to distinguish a missing entry from
a zero value.  Is there an entry for <code>"UTC"</code>
or is that zero value because it's not in the map at all?
You can discriminate with a form of multiple assignment.
Rob Pike's avatar
Rob Pike committed
1382 1383
</p>
<pre>
1384 1385
var seconds int
var ok bool
Rob Pike's avatar
Rob Pike committed
1386 1387 1388 1389 1390 1391 1392 1393
seconds, ok = timeZone[tz]
</pre>
<p>
For obvious reasons this is called the &ldquo;comma ok&rdquo; idiom.
In this example, if <code>tz</code> is present, <code>seconds</code>
will be set appropriately and <code>ok</code> will be true; if not,
<code>seconds</code> will be set to zero and <code>ok</code> will
be false.
1394
Here's a function that puts it together with a nice error report:
Rob Pike's avatar
Rob Pike committed
1395 1396 1397
</p>
<pre>
func offset(tz string) int {
1398 1399 1400
    if seconds, ok := timeZone[tz]; ok {
        return seconds
    }
1401
    log.Println("unknown time zone:", tz)
1402
    return 0
Rob Pike's avatar
Rob Pike committed
1403 1404 1405 1406 1407 1408
}
</pre>
<p>
To test for presence in the map without worrying about the actual value,
you can use the <em>blank identifier</em>, a simple underscore (<code>_</code>).
The blank identifier can be assigned or declared with any value of any type, with the
1409
value discarded harmlessly.  For testing just presence in a map, use the blank
Rob Pike's avatar
Rob Pike committed
1410 1411 1412
identifier in place of the usual variable for the value.
</p>
<pre>
1413
_, present := timeZone[tz]
Rob Pike's avatar
Rob Pike committed
1414 1415 1416 1417 1418 1419 1420 1421
</pre>
<p>
To delete a map entry, turn the multiple assignment around by placing
an extra boolean on the right; if the boolean is false, the entry
is deleted. It's safe to do this even if the key is already absent
from the map.
</p>
<pre>
1422
timeZone["PDT"] = 0, false  // Now on Standard Time
Rob Pike's avatar
Rob Pike committed
1423
</pre>
1424

1425 1426
<h3 id="printing">Printing</h3>

Rob Pike's avatar
Rob Pike committed
1427 1428 1429 1430 1431 1432 1433 1434 1435
<p>
Formatted printing in Go uses a style similar to C's <code>printf</code>
family but is richer and more general. The functions live in the <code>fmt</code>
package and have capitalized names: <code>fmt.Printf</code>, <code>fmt.Fprintf</code>,
<code>fmt.Sprintf</code> and so on.  The string functions (<code>Sprintf</code> etc.)
return a string rather than filling in a provided buffer.
</p>
<p>
You don't need to provide a format string.  For each of <code>Printf</code>,
Ian Lance Taylor's avatar
Ian Lance Taylor committed
1436
<code>Fprintf</code> and <code>Sprintf</code> there is another pair
Rob Pike's avatar
Rob Pike committed
1437 1438
of functions, for instance <code>Print</code> and <code>Println</code>.
These functions do not take a format string but instead generate a default
1439 1440 1441
format for each argument. The <code>Println</code> versions also insert a blank
between arguments and append a newline to the output while
the <code>Print</code> versions add blanks only if the operand on neither side is a string.
Rob Pike's avatar
Rob Pike committed
1442 1443 1444
In this example each line produces the same output.
</p>
<pre>
1445 1446
fmt.Printf("Hello %d\n", 23)
fmt.Fprint(os.Stdout, "Hello ", 23, "\n")
1447
fmt.Println("Hello", 23)
1448
fmt.Println(fmt.Sprint("Hello ", 23))
Rob Pike's avatar
Rob Pike committed
1449 1450
</pre>
<p>
Ian Lance Taylor's avatar
Ian Lance Taylor committed
1451 1452 1453
As mentioned in
the <a href="go_tutorial.html">tutorial</a>, <code>fmt.Fprint</code>
and friends take as a first argument any object
Rob Pike's avatar
Rob Pike committed
1454 1455 1456 1457 1458 1459 1460 1461 1462
that implements the <code>io.Writer</code> interface; the variables <code>os.Stdout</code>
and <code>os.Stderr</code> are familiar instances.
</p>
<p>
Here things start to diverge from C.  First, the numeric formats such as <code>%d</code>
do not take flags for signedness or size; instead, the printing routines use the
type of the argument to decide these properties.
</p>
<pre>
1463
var x uint64 = 1&lt;&lt;64 - 1
1464
fmt.Printf("%d %x; %d %x\n", x, x, int64(x), int64(x))
Rob Pike's avatar
Rob Pike committed
1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479
</pre>
<p>
prints
</p>
<pre>
18446744073709551615 ffffffffffffffff; -1 -1
</pre>
<p>
If you just want the default conversion, such as decimal for integers, you can use
the catchall format <code>%v</code> (for &ldquo;value&rdquo;); the result is exactly
what <code>Print</code> and <code>Println</code> would produce.
Moreover, that format can print <em>any</em> value, even arrays, structs, and
maps.  Here is a print statement for the time zone map defined in the previous section.
</p>
<pre>
1480
fmt.Printf("%v\n", timeZone)  // or just fmt.Println(timeZone)
Rob Pike's avatar
Rob Pike committed
1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495
</pre>
<p>
which gives output
</p>
<pre>
map[CST:-21600 PST:-28800 EST:-18000 UTC:0 MST:-25200]
</pre>
<p>
For maps the keys may be output in any order, of course.
When printing a struct, the modified format <code>%+v</code> annotates the
fields of the structure with their names, and for any value the alternate
format <code>%#v</code> prints the value in full Go syntax.
</p>
<pre>
type T struct {
1496
    a int
1497
    b float64
1498
    c string
Rob Pike's avatar
Rob Pike committed
1499
}
1500 1501 1502 1503 1504
t := &amp;T{ 7, -2.35, "abc\tdef" }
fmt.Printf("%v\n", t)
fmt.Printf("%+v\n", t)
fmt.Printf("%#v\n", t)
fmt.Printf("%#v\n", timeZone)
Rob Pike's avatar
Rob Pike committed
1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526
</pre>
<p>
prints
</p>
<pre>
&amp;{7 -2.35 abc   def}
&amp;{a:7 b:-2.35 c:abc     def}
&amp;main.T{a:7, b:-2.35, c:"abc\tdef"}
map[string] int{"CST":-21600, "PST":-28800, "EST":-18000, "UTC":0, "MST":-25200}
</pre>
<p>
(Note the ampersands.)
That quoted string format is also available through <code>%q</code> when
applied to a value of type <code>string</code> or <code>[]byte</code>;
the alternate format <code>%#q</code> will use backquotes instead if possible.
Also, <code>%x</code> works on strings and arrays of bytes as well as on integers,
generating a long hexadecimal string, and with
a space in the format (<code>%&nbsp;x</code>) it puts spaces between the bytes.
</p>
<p>
Another handy format is <code>%T</code>, which prints the <em>type</em> of a value.
<pre>
1527
fmt.Printf(&quot;%T\n&quot;, timeZone)
Rob Pike's avatar
Rob Pike committed
1528 1529 1530 1531 1532 1533 1534 1535 1536
</pre>
<p>
prints
</p>
<pre>
map[string] int
</pre>
<p>
If you want to control the default format for a custom type, all that's required is to define
1537
a method with the signature <code>String() string</code> on the type.
1538
For our simple type <code>T</code>, that might look like this.
Rob Pike's avatar
Rob Pike committed
1539 1540 1541
</p>
<pre>
func (t *T) String() string {
1542
    return fmt.Sprintf("%d/%g/%q", t.a, t.b, t.c)
Rob Pike's avatar
Rob Pike committed
1543
}
1544
fmt.Printf("%v\n", t)
Rob Pike's avatar
Rob Pike committed
1545 1546 1547 1548 1549 1550 1551 1552
</pre>
<p>
to print in the format
</p>
<pre>
7/-2.35/"abc\tdef"
</pre>
<p>
1553 1554 1555 1556 1557 1558
(If you need to print <em>values</em> of type <code>T</code> as well as pointers to <code>T</code>,
the receiver for <code>String</code> must be of value type; this example used a pointer because
that's more efficient and idiomatic for struct types.
See the section below on <a href="#pointers_vs_values">pointers vs. value receivers</a> for more information.)
</p>
<p>
1559
Our <code>String</code> method is able to call <code>Sprintf</code> because the
Rob Pike's avatar
Rob Pike committed
1560 1561
print routines are fully reentrant and can be used recursively.
We can even go one step further and pass a print routine's arguments directly to another such routine.
1562 1563 1564
The signature of <code>Printf</code> uses the type <code>...interface{}</code>
for its final argument to specify that an arbitrary number of parameters (of arbitrary type)
can appear after the format.
Rob Pike's avatar
Rob Pike committed
1565 1566
</p>
<pre>
1567
func Printf(format string, v ...interface{}) (n int, err error) {
Rob Pike's avatar
Rob Pike committed
1568 1569
</pre>
<p>
1570 1571 1572 1573
Within the function <code>Printf</code>, <code>v</code> acts like a variable of type
<code>[]interface{}</code> but if it is passed to another variadic function, it acts like
a regular list of arguments.
Here is the implementation of the
1574
function <code>log.Println</code> we used above. It passes its arguments directly to
Rob Pike's avatar
Rob Pike committed
1575 1576 1577
<code>fmt.Sprintln</code> for the actual formatting.
</p>
<pre>
1578 1579 1580
// Println prints to the standard logger in the manner of fmt.Println.
func Println(v ...interface{}) {
    std.Output(2, fmt.Sprintln(v...))  // Output takes parameters (int, string)
Rob Pike's avatar
Rob Pike committed
1581 1582 1583
}
</pre>
<p>
1584
We write <code>...</code> after <code>v</code> in the nested call to <code>Sprintln</code> to tell the
1585 1586 1587
compiler to treat <code>v</code> as a list of arguments; otherwise it would just pass
<code>v</code> as a single slice argument.
<p>
Rob Pike's avatar
Rob Pike committed
1588 1589 1590
There's even more to printing than we've covered here.  See the <code>godoc</code> documentation
for package <code>fmt</code> for the details.
</p>
1591 1592 1593 1594 1595 1596 1597 1598
<p>
By the way, a <code>...</code> parameter can be of a specific type, for instance <code>...int</code>
for a min function that chooses the least of a list of integers:
</p>
<pre>
func Min(a ...int) int {
    min := int(^uint(0) >> 1)  // largest int
    for _, i := range a {
1599
        if i &lt; min {
1600 1601
            min = i
        }
1602 1603 1604 1605
    }
    return min
}
</pre>
Rob Pike's avatar
Rob Pike committed
1606

1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647
<h3 id="append">Append</h3>
<p>
Now we have the missing piece we needed to explain the design of
the <code>append</code> built-in function.  The signature of <code>append</code>
is different from our custom <code>Append</code> function above.
Schematically, it's like this:
<pre>
func append(slice []<i>T</i>, elements...T) []<i>T</i>
</pre>
where <i>T</i> is a placeholder for any given type.  You can't
actually write a function in Go where the type <code>T</code>
is determined by the caller.
That's why <code>append</code> is built in: it needs support from the
compiler.
<p>
What <code>append</code> does is append the elements to the end of
the slice and return the result.  The result needs to be returned
because, as with our hand-written <code>Append</code>, the underlying
array may change.  This simple example
<pre>
x := []int{1,2,3}
x = append(x, 4, 5, 6)
fmt.Println(x)
</pre>
prints <code>[1 2 3 4 5 6]</code>.  So <code>append</code> works a
little like <code>Printf</code>, collecting an arbitrary number of
arguments.
<p>
But what if we wanted to do what our <code>Append</code> does and
append a slice to a slice?  Easy: use <code>...</code> at the call
site, just as we did in the call to <code>Output</code> above.  This
snippet produces identical output to the one above.
<pre>
x := []int{1,2,3}
y := []int{4,5,6}
x = append(x, y...)
fmt.Println(x)
</pre>
Without that <code>...</code>, it wouldn't compile because the types
would be wrong; <code>y</code> is not of type <code>int</code>.

Rob Pike's avatar
Rob Pike committed
1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678
<h2 id="initialization">Initialization</h2>

<p>
Although it doesn't look superficially very different from
initialization in C or C++, initialization in Go is more powerful.
Complex structures can be built during initialization and the ordering
issues between initialized objects in different packages are handled
correctly.
</p>

<h3 id="constants">Constants</h3>

<p>
Constants in Go are just that&mdash;constant.
They are created at compile time, even when defined as
locals in functions,
and can only be numbers, strings or booleans.
Because of the compile-time restriction, the expressions
that define them must be constant expressions,
evaluatable by the compiler.  For instance,
<code>1&lt;&lt;3</code> is a constant expression, while
<code>math.Sin(math.Pi/4)</code> is not because
the function call to <code>math.Sin</code> needs
to happen at run time.
</p>

<p>
In Go, enumerated constants are created using the <code>iota</code>
enumerator.  Since <code>iota</code> can be part of an expression and
expressions can be implicitly repeated, it is easy to build intricate
sets of values.
Rob Pike's avatar
Rob Pike committed
1679
</p>
1680 1681 1682
<pre><!--{{code "progs/eff_bytesize.go" `/^type ByteSize/` `/^\)/`}}
-->type ByteSize float64

Rob Pike's avatar
Rob Pike committed
1683
const (
1684 1685
    _           = iota // ignore first value by assigning to blank identifier
    KB ByteSize = 1 &lt;&lt; (10 * iota)
1686 1687 1688 1689
    MB
    GB
    TB
    PB
1690 1691
    EB
    ZB
1692
    YB
1693
)</pre>
Rob Pike's avatar
Rob Pike committed
1694 1695 1696 1697 1698
<p>
The ability to attach a method such as <code>String</code> to a
type makes it possible for such values to format themselves
automatically for printing, even as part of a general type.
</p>
1699 1700
<pre><!--{{code "progs/eff_bytesize.go" `/^func.*ByteSize.*String/` `/^}/`}}
-->func (b ByteSize) String() string {
1701
    switch {
1702
    case b &gt;= YB:
1703
        return fmt.Sprintf(&#34;%.2fYB&#34;, float64(b/YB))
1704
    case b &gt;= ZB:
1705
        return fmt.Sprintf(&#34;%.2fZB&#34;, float64(b/ZB))
1706
    case b &gt;= EB:
1707
        return fmt.Sprintf(&#34;%.2fEB&#34;, float64(b/EB))
1708
    case b &gt;= PB:
1709
        return fmt.Sprintf(&#34;%.2fPB&#34;, float64(b/PB))
1710
    case b &gt;= TB:
1711
        return fmt.Sprintf(&#34;%.2fTB&#34;, float64(b/TB))
1712
    case b &gt;= GB:
1713
        return fmt.Sprintf(&#34;%.2fGB&#34;, float64(b/GB))
1714
    case b &gt;= MB:
1715
        return fmt.Sprintf(&#34;%.2fMB&#34;, float64(b/MB))
1716
    case b &gt;= KB:
1717
        return fmt.Sprintf(&#34;%.2fKB&#34;, float64(b/KB))
1718
    }
1719
    return fmt.Sprintf(&#34;%.2fB&#34;, float64(b))
1720
}</pre>
Rob Pike's avatar
Rob Pike committed
1721
<p>
1722 1723 1724
(The <code>float64</code> conversions prevent <code>Sprintf</code> 
from recurring back through the <code>String</code> method for 
<code>ByteSize</code>.)
Rob Pike's avatar
Rob Pike committed
1725
The expression <code>YB</code> prints as <code>1.00YB</code>,
1726
while <code>ByteSize(1e13)</code> prints as <code>9.09TB</code>.
Rob Pike's avatar
Rob Pike committed
1727 1728 1729 1730 1731 1732 1733 1734 1735 1736
</p>

<h3 id="variables">Variables</h3>

<p>
Variables can be initialized just like constants but the
initializer can be a general expression computed at run time.
</p>
<pre>
var (
1737 1738 1739
    HOME = os.Getenv("HOME")
    USER = os.Getenv("USER")
    GOROOT = os.Getenv("GOROOT")
Rob Pike's avatar
Rob Pike committed
1740 1741 1742 1743 1744 1745
)
</pre>

<h3 id="init">The init function</h3>

<p>
1746 1747 1748
Finally, each source file can define its own niladic <code>init</code> function to
set up whatever state is required.  (Actually each file can have multiple
<code>init</code> functions.) The only restriction is that, although
Rob Pike's avatar
Rob Pike committed
1749 1750 1751
goroutines can be launched during initialization, they will not begin
execution until it completes; initialization always runs as a single thread
of execution.
1752
And finally means finally: <code>init</code> is called after all the
Rob Pike's avatar
Rob Pike committed
1753 1754 1755 1756 1757 1758
variable declarations in the package have evaluated their initializers,
and those are evaluated only after all the imported packages have been
initialized.
</p>
<p>
Besides initializations that cannot be expressed as declarations,
1759
a common use of <code>init</code> functions is to verify or repair
Rob Pike's avatar
Rob Pike committed
1760 1761 1762 1763 1764
correctness of the program state before real execution begins.
</p>

<pre>
func init() {
1765
    if USER == "" {
Rob Pike's avatar
Rob Pike committed
1766
        log.Fatal("$USER not set")
1767 1768 1769 1770 1771 1772 1773 1774 1775
    }
    if HOME == "" {
        HOME = "/usr/" + USER
    }
    if GOROOT == "" {
        GOROOT = HOME + "/go"
    }
    // GOROOT may be overridden by --goroot flag on command line.
    flag.StringVar(&amp;GOROOT, "goroot", GOROOT, "Go root directory")
Rob Pike's avatar
Rob Pike committed
1776 1777 1778 1779
}
</pre>

<h2 id="methods">Methods</h2>
Rob Pike's avatar
Rob Pike committed
1780

1781
<h3 id="pointers_vs_values">Pointers vs. Values</h3>
Rob Pike's avatar
Rob Pike committed
1782
<p>
Ian Lance Taylor's avatar
Ian Lance Taylor committed
1783
Methods can be defined for any named type that is not a pointer or an interface;
Rob Pike's avatar
Rob Pike committed
1784 1785 1786 1787 1788 1789 1790 1791 1792
the receiver does not have to be a struct.
<p>
In the discussion of slices above, we wrote an <code>Append</code>
function.  We can define it as a method on slices instead.  To do
this, we first declare a named type to which we can bind the method, and
then make the receiver for the method a value of that type.
</p>
<pre>
type ByteSlice []byte
1793

Rob Pike's avatar
Rob Pike committed
1794
func (slice ByteSlice) Append(data []byte) []byte {
1795
    // Body exactly the same as above
Rob Pike's avatar
Rob Pike committed
1796 1797 1798 1799 1800 1801 1802 1803 1804 1805
}
</pre>
<p>
This still requires the method to return the updated slice.  We can
eliminate that clumsiness by redefining the method to take a
<i>pointer</i> to a <code>ByteSlice</code> as its receiver, so the
method can overwrite the caller's slice.
</p>
<pre>
func (p *ByteSlice) Append(data []byte) {
1806 1807 1808
    slice := *p
    // Body as above, without the return.
    *p = slice
Rob Pike's avatar
Rob Pike committed
1809 1810 1811 1812 1813 1814 1815
}
</pre>
<p>
In fact, we can do even better.  If we modify our function so it looks
like a standard <code>Write</code> method, like this,
</p>
<pre>
1816
func (p *ByteSlice) Write(data []byte) (n int, err error) {
1817 1818 1819 1820
    slice := *p
    // Again as above.
    *p = slice
    return len(data), nil
Rob Pike's avatar
Rob Pike committed
1821 1822 1823 1824 1825
}
</pre>
<p>
then the type <code>*ByteSlice</code> satisfies the standard interface
<code>io.Writer</code>, which is handy.  For instance, we can
1826
print into one.
Rob Pike's avatar
Rob Pike committed
1827 1828
</p>
<pre>
1829 1830
    var b ByteSlice
    fmt.Fprintf(&amp;b, "This hour has %d days\n", 7)
Rob Pike's avatar
Rob Pike committed
1831 1832
</pre>
<p>
1833
We pass the address of a <code>ByteSlice</code>
Rob Pike's avatar
Rob Pike committed
1834 1835 1836 1837 1838 1839 1840 1841 1842 1843 1844
because only <code>*ByteSlice</code> satisfies <code>io.Writer</code>.
The rule about pointers vs. values for receivers is that value methods
can be invoked on pointers and values, but pointer methods can only be
invoked on pointers.  This is because pointer methods can modify the
receiver; invoking them on a copy of the value would cause those
modifications to be discarded.
</p>
<p>
By the way, the idea of using <code>Write</code> on a slice of bytes
is implemented by <code>bytes.Buffer</code>.
</p>
1845

Rob Pike's avatar
Rob Pike committed
1846
<h2 id="interfaces_and_types">Interfaces and other types</h2>
1847

1848 1849 1850 1851 1852 1853 1854 1855
<h3 id="interfaces">Interfaces</h3>
<p>
Interfaces in Go provide a way to specify the behavior of an
object: if something can do <em>this</em>, then it can be used
<em>here</em>.  We've seen a couple of simple examples already;
custom printers can be implemented by a <code>String</code> method
while <code>Fprintf</code> can generate output to anything
with a <code>Write</code> method.
Rob Pike's avatar
Rob Pike committed
1856
Interfaces with only one or two methods are common in Go code, and are
1857 1858 1859 1860 1861 1862 1863 1864
usually given a name derived from the method, such as <code>io.Writer</code>
for something that implements <code>Write</code>.
</p>
<p>
A type can implement multiple interfaces.
For instance, a collection can be sorted
by the routines in package <code>sort</code> if it implements
<code>sort.Interface</code>, which contains <code>Len()</code>,
Russ Cox's avatar
Russ Cox committed
1865
<code>Less(i, j int) bool</code>, and <code>Swap(i, j int)</code>,
1866 1867 1868
and it could also have a custom formatter.
In this contrived example <code>Sequence</code> satisfies both.
</p>
1869 1870
<pre><!--{{code "progs/eff_sequence.go" `/^type/` "$"}}
-->type Sequence []int
1871 1872 1873

// Methods required by sort.Interface.
func (s Sequence) Len() int {
1874
    return len(s)
1875 1876
}
func (s Sequence) Less(i, j int) bool {
1877
    return s[i] &lt; s[j]
1878 1879
}
func (s Sequence) Swap(i, j int) {
1880
    s[i], s[j] = s[j], s[i]
1881
}
1882

1883 1884
// Method for printing - sorts the elements before printing.
func (s Sequence) String() string {
1885
    sort.Sort(s)
1886
    str := &#34;[&#34;
1887
    for i, elem := range s {
1888
        if i &gt; 0 {
1889
            str += &#34; &#34;
1890 1891 1892
        }
        str += fmt.Sprint(elem)
    }
1893
    return str + &#34;]&#34;
1894
}</pre>
1895

1896
<h3 id="conversions">Conversions</h3>
1897

Rob Pike's avatar
Rob Pike committed
1898
<p>
1899 1900 1901 1902 1903 1904 1905
The <code>String</code> method of <code>Sequence</code> is recreating the
work that <code>Sprint</code> already does for slices.  We can share the
effort if we convert the <code>Sequence</code> to a plain
<code>[]int</code> before calling <code>Sprint</code>.
</p>
<pre>
func (s Sequence) String() string {
1906 1907
    sort.Sort(s)
    return fmt.Sprint([]int(s))
1908 1909 1910 1911 1912 1913 1914 1915 1916 1917 1918
}
</pre>
<p>
The conversion causes <code>s</code> to be treated as an ordinary slice
and therefore receive the default formatting.
Without the conversion, <code>Sprint</code> would find the
<code>String</code> method of <code>Sequence</code> and recur indefinitely.
Because the two types (<code>Sequence</code> and <code>[]int</code>)
are the same if we ignore the type name, it's legal to convert between them.
The conversion doesn't create a new value, it just temporarily acts
as though the existing value has a new type.
1919
(There are other legal conversions, such as from integer to floating point, that
1920 1921 1922
do create a new value.)
</p>
<p>
Rob Pike's avatar
Rob Pike committed
1923
It's an idiom in Go programs to convert the
1924 1925
type of an expression to access a different
set of methods. As an example, we could use the existing
1926
type <code>sort.IntSlice</code> to reduce the entire example
1927
to this:
Rob Pike's avatar
Rob Pike committed
1928
</p>
1929 1930
<pre>
type Sequence []int
Rob Pike's avatar
Rob Pike committed
1931

1932 1933
// Method for printing - sorts the elements before printing
func (s Sequence) String() string {
1934
    sort.IntSlice(s).Sort()
1935
    return fmt.Sprint([]int(s))
1936 1937
}
</pre>
Rob Pike's avatar
Rob Pike committed
1938
<p>
1939 1940
Now, instead of having <code>Sequence</code> implement multiple
interfaces (sorting and printing), we're using the ability of a data item to be
1941
converted to multiple types (<code>Sequence</code>, <code>sort.IntSlice</code>
1942 1943 1944 1945 1946 1947 1948 1949
and <code>[]int</code>), each of which does some part of the job.
That's more unusual in practice but can be effective.
</p>

<h3 id="generality">Generality</h3>
<p>
If a type exists only to implement an interface
and has no exported methods beyond that interface,
Rob Pike's avatar
Rob Pike committed
1950 1951 1952 1953 1954
there is no need to export the type itself.
Exporting just the interface makes it clear that
it's the behavior that matters, not the implementation,
and that other implementations with different properties
can mirror the behavior of the original type.
1955 1956 1957 1958 1959 1960 1961
It also avoids the need to repeat the documentation
on every instance of a common method.
</p>
<p>
In such cases, the constructor should return an interface value
rather than the implementing type.
As an example, in the hash libraries
1962
both <code>crc32.NewIEEE</code> and <code>adler32.New</code>
1963
return the interface type <code>hash.Hash32</code>.
Rob Pike's avatar
Rob Pike committed
1964
Substituting the CRC-32 algorithm for Adler-32 in a Go program
1965
requires only changing the constructor call;
Rob Pike's avatar
Rob Pike committed
1966 1967
the rest of the code is unaffected by the change of algorithm.
</p>
1968 1969
<p>
A similar approach allows the streaming cipher algorithms
1970
in the various <code>crypto</code> packages to be
1971
separated from the block ciphers they chain together.
1972 1973 1974 1975 1976 1977 1978 1979 1980
The <code>Block</code> interface
in the <code>crypto/cipher</code>package specifies the
behavior of a block cipher, which provides encryption
of a single block of data.
Then, by analogy with the <code>bufio</code> package,
cipher packages that implement this interface
can be used to construct streaming ciphers, represented
by the <code>Stream</code> interface, without
knowing the details of the block encryption.
1981 1982
</p>
<p>
1983
The  <code>crypto/cipher</code> interfaces look like this:
1984 1985
</p>
<pre>
1986
type Block interface {
1987 1988 1989
    BlockSize() int
    Encrypt(src, dst []byte)
    Decrypt(src, dst []byte)
1990
}
Rob Pike's avatar
Rob Pike committed
1991

1992 1993 1994 1995 1996 1997 1998 1999 2000 2001
type Stream interface {
    XORKeyStream(dst, src []byte)
}
</pre>

<p>
Here's the definition of the counter mode (CTR) stream,
which turns a block cipher into a streaming cipher; notice
that the block cipher's details are abstracted away:
</p>
Rob Pike's avatar
Rob Pike committed
2002

2003 2004 2005 2006
<pre>
// NewCTR returns a Stream that encrypts/decrypts using the given Block in
// counter mode. The length of iv must be the same as the Block's block size.
func NewCTR(block Block, iv []byte) Stream
2007 2008
</pre>
<p>
2009
<code>NewCTR</code> applies not
2010
just to one specific encryption algorithm and data source but to any
2011 2012 2013 2014
implementation of the <code>Block</code> interface and any
<code>Stream</code>.  Because they return
interface values, replacing CTR
encryption with other encryption modes is a localized change.  The constructor
Russ Cox's avatar
Russ Cox committed
2015
calls must be edited, but because the surrounding code must treat the result only
2016
as a <code>Stream</code>, it won't notice the difference.
2017
</p>
Russ Cox's avatar
Russ Cox committed
2018

Rob Pike's avatar
Rob Pike committed
2019 2020 2021 2022 2023 2024 2025 2026 2027
<h3 id="interface_methods">Interfaces and methods</h3>
<p>
Since almost anything can have methods attached, almost anything can
satisfy an interface.  One illustrative example is in the <code>http</code>
package, which defines the <code>Handler</code> interface.  Any object
that implements <code>Handler</code> can serve HTTP requests.
</p>
<pre>
type Handler interface {
2028
    ServeHTTP(ResponseWriter, *Request)
Rob Pike's avatar
Rob Pike committed
2029 2030 2031
}
</pre>
<p>
2032 2033 2034 2035 2036 2037 2038 2039
<code>ResponseWriter</code> is itself an interface that provides access
to the methods needed to return the response to the client.
Those methods include the standard <code>Write</code> method, so an
<code>http.ResponseWriter</code> can be used wherever an <code>io.Writer</code>
can be used.
<code>Request</code> is a struct containing a parsed representation
of the request from the client.
<p>
Rob Pike's avatar
Rob Pike committed
2040 2041
For brevity, let's ignore POSTs and assume HTTP requests are always
GETs; that simplification does not affect the way the handlers are
Rob Pike's avatar
Rob Pike committed
2042
set up.  Here's a trivial but complete implementation of a handler to
Rob Pike's avatar
Rob Pike committed
2043 2044 2045 2046 2047 2048
count the number of times the
page is visited.
</p>
<pre>
// Simple counter server.
type Counter struct {
2049
    n int
Rob Pike's avatar
Rob Pike committed
2050 2051
}

2052
func (ctr *Counter) ServeHTTP(w http.ResponseWriter, req *http.Request) {
2053
    ctr.n++
2054
    fmt.Fprintf(w, "counter = %d\n", ctr.n)
Rob Pike's avatar
Rob Pike committed
2055 2056 2057
}
</pre>
<p>
2058 2059
(Keeping with our theme, note how <code>Fprintf</code> can print to an
<code>http.ResponseWriter</code>.)
Rob Pike's avatar
Rob Pike committed
2060
For reference, here's how to attach such a server to a node on the URL tree.
Rob Pike's avatar
Rob Pike committed
2061
<pre>
2062
import "net/http"
Rob Pike's avatar
Rob Pike committed
2063
...
2064 2065
ctr := new(Counter)
http.Handle("/counter", ctr)
Rob Pike's avatar
Rob Pike committed
2066 2067 2068 2069 2070 2071 2072 2073 2074
</pre>
<p>
But why make <code>Counter</code> a struct?  An integer is all that's needed.
(The receiver needs to be a pointer so the increment is visible to the caller.)
</p>
<pre>
// Simpler counter server.
type Counter int

2075
func (ctr *Counter) ServeHTTP(w http.ResponseWriter, req *http.Request) {
2076
    *ctr++
2077
    fmt.Fprintf(w, "counter = %d\n", *ctr)
Rob Pike's avatar
Rob Pike committed
2078 2079 2080 2081 2082 2083 2084 2085 2086
}
</pre>
<p>
What if your program has some internal state that needs to be notified that a page
has been visited?  Tie a channel to the web page.
</p>
<pre>
// A channel that sends a notification on each visit.
// (Probably want the channel to be buffered.)
Rob Pike's avatar
Rob Pike committed
2087
type Chan chan *http.Request
Rob Pike's avatar
Rob Pike committed
2088

2089
func (ch Chan) ServeHTTP(w http.ResponseWriter, req *http.Request) {
2090
    ch &lt;- req
2091
    fmt.Fprint(w, "notification sent")
Rob Pike's avatar
Rob Pike committed
2092 2093 2094 2095 2096
}
</pre>
<p>
Finally, let's say we wanted to present on <code>/args</code> the arguments
used when invoking the server binary.
Rob Pike's avatar
Rob Pike committed
2097
It's easy to write a function to print the arguments.
Rob Pike's avatar
Rob Pike committed
2098 2099 2100
</p>
<pre>
func ArgServer() {
2101
    for _, s := range os.Args {
2102 2103
        fmt.Println(s)
    }
Rob Pike's avatar
Rob Pike committed
2104 2105 2106 2107 2108
}
</pre>
<p>
How do we turn that into an HTTP server?  We could make <code>ArgServer</code>
a method of some type whose value we ignore, but there's a cleaner way.
Rob Pike's avatar
Rob Pike committed
2109 2110
Since we can define a method for any type except pointers and interfaces,
we can write a method for a function.
Rob Pike's avatar
Rob Pike committed
2111 2112 2113 2114 2115 2116 2117
The <code>http</code> package contains this code:
</p>
<pre>
// The HandlerFunc type is an adapter to allow the use of
// ordinary functions as HTTP handlers.  If f is a function
// with the appropriate signature, HandlerFunc(f) is a
// Handler object that calls f.
2118
type HandlerFunc func(ResponseWriter, *Request)
Rob Pike's avatar
Rob Pike committed
2119 2120

// ServeHTTP calls f(c, req).
2121 2122
func (f HandlerFunc) ServeHTTP(w ResponseWriter, req *Request) {
    f(w, req)
Rob Pike's avatar
Rob Pike committed
2123 2124 2125 2126 2127 2128
}
</pre>
<p>
<code>HandlerFunc</code> is a type with a method, <code>ServeHTTP</code>,
so values of that type can serve HTTP requests.  Look at the implementation
of the method: the receiver is a function, <code>f</code>, and the method
Rob Pike's avatar
Rob Pike committed
2129
calls <code>f</code>.  That may seem odd but it's not that different from, say,
Rob Pike's avatar
Rob Pike committed
2130 2131 2132
the receiver being a channel and the method sending on the channel.
</p>
<p>
Rob Pike's avatar
Rob Pike committed
2133 2134
To make <code>ArgServer</code> into an HTTP server, we first modify it
to have the right signature.
Rob Pike's avatar
Rob Pike committed
2135 2136 2137
</p>
<pre>
// Argument server.
2138
func ArgServer(w http.ResponseWriter, req *http.Request) {
2139
    for _, s := range os.Args {
2140
        fmt.Fprintln(w, s)
2141
    }
Rob Pike's avatar
Rob Pike committed
2142 2143 2144
}
</pre>
<p>
Rob Pike's avatar
Rob Pike committed
2145 2146
<code>ArgServer</code> now has same signature as <code>HandlerFunc</code>,
so it can be converted to that type to access its methods,
2147 2148
just as we converted <code>Sequence</code> to <code>IntSlice</code>
to access <code>IntSlice.Sort</code>.
Rob Pike's avatar
Rob Pike committed
2149
The code to set it up is concise:
Rob Pike's avatar
Rob Pike committed
2150 2151
</p>
<pre>
2152
http.Handle("/args", http.HandlerFunc(ArgServer))
Rob Pike's avatar
Rob Pike committed
2153 2154 2155
</pre>
<p>
When someone visits the page <code>/args</code>,
Rob Pike's avatar
Rob Pike committed
2156 2157
the handler installed at that page has value <code>ArgServer</code>
and type <code>HandlerFunc</code>.
Rob Pike's avatar
Rob Pike committed
2158
The HTTP server will invoke the method <code>ServeHTTP</code>
Rob Pike's avatar
Rob Pike committed
2159
of that type, with <code>ArgServer</code> as the receiver, which will in turn call
Rob Pike's avatar
Rob Pike committed
2160
<code>ArgServer</code> (via the invocation <code>f(c, req)</code>
Rob Pike's avatar
Rob Pike committed
2161 2162
inside <code>HandlerFunc.ServeHTTP</code>).
The arguments will then be displayed.
Rob Pike's avatar
Rob Pike committed
2163 2164
</p>
<p>
Rob Pike's avatar
Rob Pike committed
2165
In this section we have made an HTTP server from a struct, an integer,
Rob Pike's avatar
Rob Pike committed
2166 2167 2168 2169
a channel, and a function, all because interfaces are just sets of
methods, which can be defined for (almost) any type.
</p>

Rob Pike's avatar
Rob Pike committed
2170 2171 2172 2173 2174 2175 2176 2177 2178 2179 2180 2181 2182 2183 2184
<h2 id="embedding">Embedding</h2>

<p>
Go does not provide the typical, type-driven notion of subclassing,
but it does have the ability to &ldquo;borrow&rdquo; pieces of an
implementation by <em>embedding</em> types within a struct or
interface.
</p>
<p>
Interface embedding is very simple.
We've mentioned the <code>io.Reader</code> and <code>io.Writer</code> interfaces before;
here are their definitions.
</p>
<pre>
type Reader interface {
2185
    Read(p []byte) (n int, err error)
Rob Pike's avatar
Rob Pike committed
2186 2187 2188
}

type Writer interface {
2189
    Write(p []byte) (n int, err error)
Rob Pike's avatar
Rob Pike committed
2190 2191 2192 2193 2194 2195 2196 2197 2198 2199 2200 2201
}
</pre>
<p>
The <code>io</code> package also exports several other interfaces
that specify objects that can implement several such methods.
For instance, there is <code>io.ReadWriter</code>, an interface
containing both <code>Read</code> and <code>Write</code>.
We could specify <code>io.ReadWriter</code> by listing the
two methods explicitly, but it's easier and more evocative
to embed the two interfaces to form the new one, like this:
</p>
<pre>
2202
// ReadWriter is the interface that combines the Reader and Writer interfaces.
Rob Pike's avatar
Rob Pike committed
2203
type ReadWriter interface {
2204 2205
    Reader
    Writer
Rob Pike's avatar
Rob Pike committed
2206 2207 2208 2209 2210 2211 2212 2213 2214 2215 2216 2217 2218 2219 2220 2221 2222 2223 2224 2225 2226 2227 2228
}
</pre>
<p>
This says just what it looks like: A <code>ReadWriter</code> can do
what a <code>Reader</code> does <em>and</em> what a <code>Writer</code>
does; it is a union of the embedded interfaces (which must be disjoint
sets of methods).
Only interfaces can be embedded within interfaces.
<p>
The same basic idea applies to structs, but with more far-reaching
implications.  The <code>bufio</code> package has two struct types,
<code>bufio.Reader</code> and <code>bufio.Writer</code>, each of
which of course implements the analogous interfaces from package
<code>io</code>.
And <code>bufio</code> also implements a buffered reader/writer,
which it does by combining a reader and a writer into one struct
using embedding: it lists the types within the struct
but does not give them field names.
</p>
<pre>
// ReadWriter stores pointers to a Reader and a Writer.
// It implements io.ReadWriter.
type ReadWriter struct {
2229 2230
    *Reader  // *bufio.Reader
    *Writer  // *bufio.Writer
Rob Pike's avatar
Rob Pike committed
2231 2232 2233
}
</pre>
<p>
2234 2235 2236 2237
The embedded elements are pointers to structs and of course
must be initialized to point to valid structs before they
can be used.
The <code>ReadWriter</code> struct could be written as
Rob Pike's avatar
Rob Pike committed
2238 2239 2240
</p>
<pre>
type ReadWriter struct {
2241 2242
    reader *Reader
    writer *Writer
Rob Pike's avatar
Rob Pike committed
2243 2244 2245 2246 2247 2248 2249 2250
}
</pre>
<p>
but then to promote the methods of the fields and to
satisfy the <code>io</code> interfaces, we would also need
to provide forwarding methods, like this:
</p>
<pre>
2251
func (rw *ReadWriter) Read(p []byte) (n int, err error) {
2252
    return rw.reader.Read(p)
Rob Pike's avatar
Rob Pike committed
2253 2254 2255 2256 2257 2258 2259 2260 2261 2262 2263 2264
}
</pre>
<p>
By embedding the structs directly, we avoid this bookkeeping.
The methods of embedded types come along for free, which means that <code>bufio.ReadWriter</code>
not only has the methods of <code>bufio.Reader</code> and <code>bufio.Writer</code>,
it also satisfies all three interfaces:
<code>io.Reader</code>,
<code>io.Writer</code>, and
<code>io.ReadWriter</code>.
</p>
<p>
Rob Pike's avatar
Rob Pike committed
2265
There's an important way in which embedding differs from subclassing.  When we embed a type,
2266 2267
the methods of that type become methods of the outer type,
but when they are invoked the receiver of the method is the inner type, not the outer one.
Rob Pike's avatar
Rob Pike committed
2268
In our example, when the <code>Read</code> method of a <code>bufio.ReadWriter</code> is
Rob Pike's avatar
Rob Pike committed
2269
invoked, it has exactly the same effect as the forwarding method written out above;
Rob Pike's avatar
Rob Pike committed
2270 2271 2272
the receiver is the <code>reader</code> field of the <code>ReadWriter</code>, not the
<code>ReadWriter</code> itself.
</p>
Rob Pike's avatar
Rob Pike committed
2273 2274 2275 2276 2277 2278
<p>
Embedding can also be a simple convenience.
This example shows an embedded field alongside a regular, named field.
</p>
<pre>
type Job struct {
2279 2280
    Command string
    *log.Logger
Rob Pike's avatar
Rob Pike committed
2281 2282 2283 2284 2285
}
</pre>
<p>
The <code>Job</code> type now has the <code>Log</code>, <code>Logf</code>
and other
2286
methods of <code>*log.Logger</code>.  We could have given the <code>Logger</code>
2287 2288 2289
a field name, of course, but it's not necessary to do so.  And now, once
initialized, we can
log to the <code>Job</code>:
Rob Pike's avatar
Rob Pike committed
2290 2291
</p>
<pre>
2292
job.Log("starting now...")
Rob Pike's avatar
Rob Pike committed
2293 2294
</pre>
<p>
2295
The <code>Logger</code> is a regular field of the struct and we can initialize
2296
it in the usual way with a constructor,
2297 2298 2299
</p>
<pre>
func NewJob(command string, logger *log.Logger) *Job {
2300
    return &amp;Job{command, logger}
2301 2302 2303
}
</pre>
<p>
2304 2305 2306
or with a composite literal,
</p>
<pre>
2307
job := &amp;Job{command, log.New(os.Stderr, "Job: ", log.Ldate)}
2308 2309
</pre>
<p>
Rob Pike's avatar
Rob Pike committed
2310 2311 2312 2313 2314 2315 2316
If we need to refer to an embedded field directly, the type name of the field,
ignoring the package qualifier, serves as a field name.  If we needed to access the
<code>*log.Logger</code> of a <code>Job</code> variable <code>job</code>,
we would write <code>job.Logger</code>.
This would be useful if we wanted to refine the methods of <code>Logger</code>.
</p>
<pre>
2317
func (job *Job) Logf(format string, args ...interface{}) {
2318
    job.Logger.Logf("%q: %s", job.Command, fmt.Sprintf(format, args))
Rob Pike's avatar
Rob Pike committed
2319 2320 2321 2322 2323 2324 2325 2326 2327 2328 2329 2330
}
</pre>
<p>
Embedding types introduces the problem of name conflicts but the rules to resolve
them are simple.
First, a field or method <code>X</code> hides any other item <code>X</code> in a more deeply
nested part of the type.
If <code>log.Logger</code> contained a field or method called <code>Command</code>, the <code>Command</code> field
of <code>Job</code> would dominate it.
</p>
<p>
Second, if the same name appears at the same nesting level, it is usually an error;
2331
it would be erroneous to embed <code>log.Logger</code> if the <code>Job</code> struct
Rob Pike's avatar
Rob Pike committed
2332 2333 2334
contained another field or method called <code>Logger</code>.
However, if the duplicate name is never mentioned in the program outside the type definition, it is OK.
This qualification provides some protection against changes made to types embedded from outside; there
Rob Pike's avatar
Rob Pike committed
2335 2336
is no problem if a field is added that conflicts with another field in another subtype if neither field
is ever used.
Rob Pike's avatar
Rob Pike committed
2337
</p>
Rob Pike's avatar
Rob Pike committed
2338 2339


2340 2341 2342 2343
<h2 id="concurrency">Concurrency</h2>

<h3 id="sharing">Share by communicating</h3>

Rob Pike's avatar
Rob Pike committed
2344 2345 2346 2347
<p>
Concurrent programming is a large topic and there is space only for some
Go-specific highlights here.
</p>
2348 2349 2350 2351 2352 2353 2354 2355 2356 2357 2358 2359 2360 2361 2362 2363 2364 2365 2366 2367
<p>
Concurrent programming in many environments is made difficult by the
subtleties required to implement correct access to shared variables.  Go encourages
a different approach in which shared values are passed around on channels
and, in fact, never actively shared by separate threads of execution.
Only one goroutine has access to the value at any given time.
Data races cannot occur, by design.
To encourage this way of thinking we have reduced it to a slogan:
</p>
<blockquote>
Do not communicate by sharing memory;
instead, share memory by communicating.
</blockquote>
<p>
This approach can be taken too far.  Reference counts may be best done
by putting a mutex around an integer variable, for instance.  But as a
high-level approach, using channels to control access makes it easier
to write clear, correct programs.
</p>
<p>
Rob Pike's avatar
Rob Pike committed
2368
One way to think about this model is to consider a typical single-threaded
2369 2370 2371
program running on one CPU. It has no need for synchronization primitives.
Now run another such instance; it too needs no synchronization.  Now let those
two communicate; if the communication is the synchronizer, there's still no need
Rob Pike's avatar
Rob Pike committed
2372
for other synchronization.  Unix pipelines, for example, fit this model
Rob Pike's avatar
Rob Pike committed
2373
perfectly.  Although Go's approach to concurrency originates in Hoare's
2374 2375 2376 2377 2378 2379
Communicating Sequential Processes (CSP),
it can also be seen as a type-safe generalization of Unix pipes.
</p>

<h3 id="goroutines">Goroutines</h3>

Rob Pike's avatar
Rob Pike committed
2380 2381 2382 2383 2384 2385 2386 2387 2388 2389 2390 2391 2392 2393 2394 2395 2396 2397 2398 2399 2400 2401 2402 2403 2404
<p>
They're called <em>goroutines</em> because the existing
terms&mdash;threads, coroutines, processes, and so on&mdash;convey
inaccurate connotations.  A goroutine has a simple model: it is a
function executing in parallel with other goroutines in the same
address space.  It is lightweight, costing little more than the
allocation of stack space.
And the stacks start small, so they are cheap, and grow
by allocating (and freeing) heap storage as required.
</p>
<p>
Goroutines are multiplexed onto multiple OS threads so if one should
block, such as while waiting for I/O, others continue to run.  Their
design hides many of the complexities of thread creation and
management.
</p>
<p>
Prefix a function or method call with the <code>go</code>
keyword to run the call in a new goroutine.
When the call completes, the goroutine
exits, silently.  (The effect is similar to the Unix shell's
<code>&amp;</code> notation for running a command in the
background.)
</p>
<pre>
2405
go list.Sort()  // run list.Sort in parallel; don't wait for it. 
Rob Pike's avatar
Rob Pike committed
2406 2407 2408 2409 2410
</pre>
<p>
A function literal can be handy in a goroutine invocation.
<pre>
func Announce(message string, delay int64) {
2411 2412 2413 2414
    go func() {
        time.Sleep(delay)
        fmt.Println(message)
    }()  // Note the parentheses - must call the function.
Rob Pike's avatar
Rob Pike committed
2415 2416 2417
}
</pre>
<p>
Rob Pike's avatar
Rob Pike committed
2418
In Go, function literals are closures: the implementation makes
Rob Pike's avatar
Rob Pike committed
2419 2420 2421 2422 2423 2424
sure the variables referred to by the function survive as long as they are active.
<p>
These examples aren't too practical because the functions have no way of signaling
completion.  For that, we need channels.
</p>

2425 2426
<h3 id="channels">Channels</h3>

Rob Pike's avatar
Rob Pike committed
2427 2428 2429 2430 2431 2432
<p>
Like maps, channels are a reference type and are allocated with <code>make</code>.
If an optional integer parameter is provided, it sets the buffer size for the channel.
The default is zero, for an unbuffered or synchronous channel.
</p>
<pre>
2433 2434 2435
ci := make(chan int)            // unbuffered channel of integers
cj := make(chan int, 0)         // unbuffered channel of integers
cs := make(chan *os.File, 100)  // buffered channel of pointers to Files
Rob Pike's avatar
Rob Pike committed
2436 2437 2438 2439 2440 2441 2442 2443 2444 2445 2446 2447
</pre>
<p>
Channels combine communication&mdash;the exchange of a value&mdash;with
synchronization&mdash;guaranteeing that two calculations (goroutines) are in
a known state.
</p>
<p>
There are lots of nice idioms using channels.  Here's one to get us started.
In the previous section we launched a sort in the background. A channel
can allow the launching goroutine to wait for the sort to complete.
</p>
<pre>
2448
c := make(chan int)  // Allocate a channel.
Rob Pike's avatar
Rob Pike committed
2449 2450
// Start the sort in a goroutine; when it completes, signal on the channel.
go func() {
2451 2452 2453 2454 2455
    list.Sort()
    c &lt;- 1  // Send a signal; value does not matter. 
}()
doSomethingForAWhile()
&lt;-c   // Wait for sort to finish; discard sent value.
Rob Pike's avatar
Rob Pike committed
2456 2457 2458 2459 2460 2461
</pre>
<p>
Receivers always block until there is data to receive.
If the channel is unbuffered, the sender blocks until the receiver has
received the value.
If the channel has a buffer, the sender blocks only until the
Ian Lance Taylor's avatar
Ian Lance Taylor committed
2462 2463
value has been copied to the buffer; if the buffer is full, this
means waiting until some receiver has retrieved a value.
Rob Pike's avatar
Rob Pike committed
2464 2465 2466 2467 2468
</p>
<p>
A buffered channel can be used like a semaphore, for instance to
limit throughput.  In this example, incoming requests are passed
to <code>handle</code>, which sends a value into the channel, processes
Rob Pike's avatar
Rob Pike committed
2469
the request, and then receives a value from the channel.
Rob Pike's avatar
Rob Pike committed
2470 2471 2472 2473 2474 2475 2476
The capacity of the channel buffer limits the number of
simultaneous calls to <code>process</code>.
</p>
<pre>
var sem = make(chan int, MaxOutstanding)

func handle(r *Request) {
2477
    sem &lt;- 1    // Wait for active queue to drain.
2478
    process(r)  // May take a long time.
2479
    &lt;-sem       // Done; enable next request to run.
Rob Pike's avatar
Rob Pike committed
2480 2481 2482 2483
}

func Serve(queue chan *Request) {
    for {
2484
        req := &lt;-queue
2485
        go handle(req)  // Don't wait for handle to finish.
Rob Pike's avatar
Rob Pike committed
2486 2487 2488 2489 2490 2491 2492 2493 2494 2495 2496 2497 2498 2499 2500
    }
}
</pre>
<p>
Here's the same idea implemented by starting a fixed
number of <code>handle</code> goroutines all reading from the request
channel.
The number of goroutines limits the number of simultaneous
calls to <code>process</code>.
This <code>Serve</code> function also accepts a channel on which
it will be told to exit; after launching the goroutines it blocks
receiving from that channel.
</p>
<pre>
func handle(queue chan *Request) {
2501 2502 2503
    for r := range queue {
        process(r)
    }
Rob Pike's avatar
Rob Pike committed
2504 2505 2506
}

func Serve(clientRequests chan *clientRequests, quit chan bool) {
2507
    // Start handlers
2508
    for i := 0; i &lt; MaxOutstanding; i++ {
2509 2510
        go handle(clientRequests)
    }
2511
    &lt;-quit  // Wait to be told to exit.
Rob Pike's avatar
Rob Pike committed
2512 2513 2514 2515 2516 2517 2518 2519 2520 2521 2522 2523 2524 2525 2526 2527 2528 2529
}
</pre>

<h3 id="chan_of_chan">Channels of channels</h3>
<p>
One of the most important properties of Go is that
a channel is a first-class value that can be allocated and passed
around like any other.  A common use of this property is
to implement safe, parallel demultiplexing.
<p>
In the example in the previous section, <code>handle</code> was
an idealized handler for a request but we didn't define the
type it was handling.  If that type includes a channel on which
to reply, each client can provide its own path for the answer.
Here's a schematic definition of type <code>Request</code>.
</p>
<pre>
type Request struct {
2530 2531 2532
    args        []int
    f           func([]int) int
    resultChan  chan int
Rob Pike's avatar
Rob Pike committed
2533 2534 2535 2536 2537 2538 2539 2540
}
</pre>
<p>
The client provides a function and its arguments, as well as
a channel inside the request object on which to receive the answer.
</p>
<pre>
func sum(a []int) (s int) {
2541 2542 2543 2544
    for _, v := range a {
        s += v
    }
    return
Rob Pike's avatar
Rob Pike committed
2545 2546 2547 2548
}

request := &amp;Request{[]int{3, 4, 5}, sum, make(chan int)}
// Send request
2549
clientRequests &lt;- request
Rob Pike's avatar
Rob Pike committed
2550
// Wait for response.
2551
fmt.Printf("answer: %d\n", &lt;-request.resultChan)
Rob Pike's avatar
Rob Pike committed
2552 2553 2554 2555 2556 2557
</pre>
<p>
On the server side, the handler function is the only thing that changes.
</p>
<pre>
func handle(queue chan *Request) {
2558
    for req := range queue {
2559
        req.resultChan &lt;- req.f(req.args)
2560
    }
Rob Pike's avatar
Rob Pike committed
2561 2562 2563 2564 2565 2566 2567 2568 2569 2570 2571 2572 2573 2574 2575 2576
}
</pre>
<p>
There's clearly a lot more to do to make it realistic, but this
code is a framework for a rate-limited, parallel, non-blocking RPC
system, and there's not a mutex in sight.
</p>

<h3 id="parallel">Parallelization</h3>
<p>
Another application of these ideas is to parallelize a calculation
across multiple CPU cores.  If the calculation can be broken into
separate pieces, it can be parallelized, with a channel to signal
when each piece completes.
</p>
<p>
Rob Pike's avatar
Rob Pike committed
2577
Let's say we have an expensive operation to perform on a vector of items,
Rob Pike's avatar
Rob Pike committed
2578 2579 2580 2581
and that the value of the operation on each item is independent,
as in this idealized example.
</p>
<pre>
Rob Pike's avatar
Rob Pike committed
2582
type Vector []float64
Rob Pike's avatar
Rob Pike committed
2583

Rob Pike's avatar
Rob Pike committed
2584
// Apply the operation to v[i], v[i+1] ... up to v[n-1].
Rob Pike's avatar
Rob Pike committed
2585
func (v Vector) DoSome(i, n int, u Vector, c chan int) {
2586
    for ; i &lt; n; i++ {
Rob Pike's avatar
Rob Pike committed
2587 2588
        v[i] += u.Op(v[i])
    }
2589
    c &lt;- 1    // signal that this piece is done
Rob Pike's avatar
Rob Pike committed
2590 2591 2592 2593 2594 2595 2596 2597 2598
}
</pre>
<p>
We launch the pieces independently in a loop, one per CPU.
They can complete in any order but it doesn't matter; we just
count the completion signals by draining the channel after
launching all the goroutines.
</p>
<pre>
2599
const NCPU = 4  // number of CPU cores
Rob Pike's avatar
Rob Pike committed
2600

Rob Pike's avatar
Rob Pike committed
2601
func (v Vector) DoAll(u Vector) {
2602
    c := make(chan int, NCPU)  // Buffering optional but sensible.
2603
    for i := 0; i &lt; NCPU; i++ {
2604
        go v.DoSome(i*len(v)/NCPU, (i+1)*len(v)/NCPU, u, c)
Rob Pike's avatar
Rob Pike committed
2605 2606
    }
    // Drain the channel.
2607 2608
    for i := 0; i &lt; NCPU; i++ {
        &lt;-c    // wait for one task to complete
Rob Pike's avatar
Rob Pike committed
2609 2610 2611 2612 2613 2614
    }
    // All done.
}

</pre>

Rob Pike's avatar
Rob Pike committed
2615 2616 2617 2618 2619 2620 2621 2622 2623 2624 2625
<p>
The current implementation of <code>gc</code> (<code>6g</code>, etc.)
will not parallelize this code by default.
It dedicates only a single core to user-level processing.  An
arbitrary number of goroutines can be blocked in system calls, but
by default only one can be executing user-level code at any time.
It should be smarter and one day it will be smarter, but until it
is if you want CPU parallelism you must tell the run-time
how many goroutines you want executing code simultaneously.  There
are two related ways to do this.  Either run your job with environment
variable <code>GOMAXPROCS</code> set to the number of cores to use
2626
or import the <code>runtime</code> package and call
Rob Pike's avatar
Rob Pike committed
2627
<code>runtime.GOMAXPROCS(NCPU)</code>.
2628 2629
A helpful value might be <code>runtime.NumCPU()</code>, which reports the number
of logical CPUs on the local machine.
Rob Pike's avatar
Rob Pike committed
2630 2631 2632
Again, this requirement is expected to be retired as the scheduling and run-time improve.
</p>

2633 2634 2635
<h3 id="leaky_buffer">A leaky buffer</h3>

<p>
Rob Pike's avatar
Rob Pike committed
2636
The tools of concurrent programming can even make non-concurrent
2637 2638 2639 2640 2641 2642 2643 2644 2645
ideas easier to express.  Here's an example abstracted from an RPC
package.  The client goroutine loops receiving data from some source,
perhaps a network.  To avoid allocating and freeing buffers, it keeps
a free list, and uses a buffered channel to represent it.  If the
channel is empty, a new buffer gets allocated.
Once the message buffer is ready, it's sent to the server on
<code>serverChan</code>.
</p>
<pre>
Russ Cox's avatar
Russ Cox committed
2646 2647
var freeList = make(chan *Buffer, 100)
var serverChan = make(chan *Buffer)
2648 2649

func client() {
2650
    for {
2651 2652 2653 2654 2655 2656 2657
        var b *Buffer
        // Grab a buffer if available; allocate if not.
        select {
        case b = &lt;-freeList:
            // Got one; nothing more to do.
        default:
            // None free, so allocate a new one.
2658 2659
            b = new(Buffer)
        }
2660 2661
        load(b)              // Read next message from the net.
        serverChan &lt;- b      // Send to server.
2662
    }
2663 2664 2665
}
</pre>
<p>
2666
The server loop receives each message from the client, processes it,
2667 2668 2669 2670
and returns the buffer to the free list.
</p>
<pre>
func server() {
2671
    for {
2672
        b := &lt;-serverChan    // Wait for work.
2673
        process(b)
2674 2675 2676 2677 2678 2679 2680
        // Reuse buffer if there's room.
        select {
        case freeList &lt;- b:
            // Buffer on free list; nothing more to do.
        default:
            // Free list full, just carry on.
        }
2681
    }
2682 2683 2684
}
</pre>
<p>
2685 2686 2687
The client attempts to retrieve a buffer from <code>freeList</code>;
if none is available, it allocates a fresh one.
The server's send to <code>freeList</code> puts <code>b</code> back
2688 2689 2690
on the free list unless the list is full, in which case the
buffer is dropped on the floor to be reclaimed by
the garbage collector.
2691 2692 2693
(The <code>default</code> clauses in the <code>select</code>
statements execute when no other case is ready,
meaning that the <code>selects</code> never block.)
2694 2695 2696 2697 2698
This implementation builds a leaky bucket free list
in just a few lines, relying on the buffered channel and
the garbage collector for bookkeeping.
</p>

Rob Pike's avatar
Rob Pike committed
2699
<h2 id="errors">Errors</h2>
Russ Cox's avatar
Russ Cox committed
2700

Rob Pike's avatar
Rob Pike committed
2701 2702 2703 2704
<p>
Library routines must often return some sort of error indication to
the caller.  As mentioned earlier, Go's multivalue return makes it
easy to return a detailed error description alongside the normal
2705 2706
return value.  By convention, errors have type <code>error</code>,
a simple built-in interface.
Rob Pike's avatar
Rob Pike committed
2707 2708
</p>
<pre>
2709 2710
type error interface {
    Error() string
Rob Pike's avatar
Rob Pike committed
2711 2712 2713 2714 2715 2716 2717 2718
}
</pre>
<p>
A library writer is free to implement this interface with a
richer model under the covers, making it possible not only
to see the error but also to provide some context.
For example, <code>os.Open</code> returns an <code>os.PathError</code>.
</p>
Russ Cox's avatar
Russ Cox committed
2719
<pre>
Rob Pike's avatar
Rob Pike committed
2720 2721 2722
// PathError records an error and the operation and
// file path that caused it.
type PathError struct {
2723 2724
    Op string    // "open", "unlink", etc.
    Path string  // The associated file.
2725
    Err error    // Returned by the system call.
Rob Pike's avatar
Rob Pike committed
2726 2727
}

2728 2729
func (e *PathError) Error() string {
    return e.Op + " " + e.Path + ": " + e.Err.Error()
Rob Pike's avatar
Rob Pike committed
2730
}
Russ Cox's avatar
Russ Cox committed
2731
</pre>
Rob Pike's avatar
Rob Pike committed
2732
<p>
2733
<code>PathError</code>'s <code>Error</code> generates
Rob Pike's avatar
Rob Pike committed
2734
a string like this:
Rob Pike's avatar
Rob Pike committed
2735
</p>
Russ Cox's avatar
Russ Cox committed
2736
<pre>
Rob Pike's avatar
Rob Pike committed
2737
open /etc/passwx: no such file or directory
Russ Cox's avatar
Russ Cox committed
2738
</pre>
Rob Pike's avatar
Rob Pike committed
2739
<p>
Rob Pike's avatar
Rob Pike committed
2740 2741 2742 2743 2744
Such an error, which includes the problematic file name, the
operation, and the operating system error it triggered, is useful even
if printed far from the call that caused it;
it is much more informative than the plain
"no such file or directory".
Rob Pike's avatar
Rob Pike committed
2745 2746
</p>

2747 2748 2749 2750 2751 2752 2753
<p>
When feasible, error strings should identify their origin, such as by having
a prefix naming the package that generated the error.  For example, in package
image, the string representation for a decoding error due to an unknown format
is "image: unknown format".
</p>

Rob Pike's avatar
Rob Pike committed
2754 2755
<p>
Callers that care about the precise error details can
Rob Pike's avatar
Rob Pike committed
2756
use a type switch or a type assertion to look for specific
Rob Pike's avatar
Rob Pike committed
2757
errors and extract details.  For <code>PathErrors</code>
2758
this might include examining the internal <code>Err</code>
Rob Pike's avatar
Rob Pike committed
2759
field for recoverable failures.
Rob Pike's avatar
Rob Pike committed
2760
</p>
Russ Cox's avatar
Russ Cox committed
2761

Rob Pike's avatar
Rob Pike committed
2762
<pre>
2763
for try := 0; try &lt; 2; try++ {
2764
    file, err = os.Open(filename)
2765 2766 2767
    if err == nil {
        return
    }
2768
    if e, ok := err.(*os.PathError); ok &amp;&amp; e.Err == os.ENOSPC {
2769 2770 2771 2772
        deleteTempFiles()  // Recover some space.
        continue
    }
    return
Rob Pike's avatar
Rob Pike committed
2773 2774 2775
}
</pre>

2776 2777 2778 2779 2780 2781 2782 2783 2784 2785 2786 2787
<p>
The second <code>if</code> statement here is idiomatic Go.
The type assertion <code>err.(*os.PathError)</code> is
checked with the "comma ok" idiom (mentioned <a href="#maps">earlier</a>
in the context of examining maps).
If the type assertion fails, <code>ok</code> will be false, and <code>e</code>
will be <code>nil</code>.
If it succeeds,  <code>ok</code> will be true, which means the
error was of type <code>*os.PathError</code>, and then so is <code>e</code>,
which we can examine for more information about the error.
</p>

Rob Pike's avatar
Rob Pike committed
2788
<h3 id="panic">Panic</h3>
2789 2790

<p>
Rob Pike's avatar
Rob Pike committed
2791
The usual way to report an error to a caller is to return an
2792
<code>error</code> as an extra return value.  The canonical
Rob Pike's avatar
Rob Pike committed
2793
<code>Read</code> method is a well-known instance; it returns a byte
2794
count and an <code>error</code>.  But what if the error is
Rob Pike's avatar
Rob Pike committed
2795 2796 2797 2798 2799 2800 2801 2802 2803 2804 2805 2806 2807 2808 2809 2810 2811 2812
unrecoverable?  Sometimes the program simply cannot continue.
</p>

<p>
For this purpose, there is a built-in function <code>panic</code>
that in effect creates a run-time error that will stop the program
(but see the next section).  The function takes a single argument
of arbitrary type&mdash;often a string&mdash;to be printed as the
program dies.  It's also a way to indicate that something impossible has
happened, such as exiting an infinite loop.  In fact, the compiler
recognizes a <code>panic</code> at the end of a function and
suppresses the usual check for a <code>return</code> statement.
</p>


<pre>
// A toy implementation of cube root using Newton's method.
func CubeRoot(x float64) float64 {
2813
    z := x/3   // Arbitrary initial value
2814
    for i := 0; i &lt; 1e6; i++ {
Rob Pike's avatar
Rob Pike committed
2815 2816 2817 2818 2819 2820 2821
        prevz := z
        z -= (z*z*z-x) / (3*z*z)
        if veryClose(z, prevz) {
            return z
        }
    }
    // A million iterations has not converged; something is wrong.
2822
    panic(fmt.Sprintf("CubeRoot(%g) did not converge", x))
Rob Pike's avatar
Rob Pike committed
2823 2824 2825 2826 2827 2828 2829 2830 2831 2832 2833 2834 2835 2836 2837 2838 2839 2840 2841 2842 2843 2844 2845 2846 2847 2848
}
</pre>

<p>
This is only an example but real library functions should
avoid <code>panic</code>.  If the problem can be masked or worked
around, it's always better to let things continue to run rather
than taking down the whole program.  One possible counterexample
is during initialization: if the library truly cannot set itself up,
it might be reasonable to panic, so to speak.
</p>

<pre>
var user = os.Getenv("USER")

func init() {
    if user == "" {
        panic("no value for $USER")
    }
}
</pre>

<h3 id="recover">Recover</h3>

<p>
When <code>panic</code> is called, including implicitly for run-time
Robert Griesemer's avatar
Robert Griesemer committed
2849
errors such as indexing an array out of bounds or failing a type
Rob Pike's avatar
Rob Pike committed
2850 2851 2852 2853 2854 2855 2856 2857 2858 2859 2860 2861 2862 2863 2864 2865 2866 2867 2868 2869 2870
assertion, it immediately stops execution of the current function
and begins unwinding the stack of the goroutine, running any deferred
functions along the way.  If that unwinding reaches the top of the
goroutine's stack, the program dies.  However, it is possible to
use the built-in function <code>recover</code> to regain control
of the goroutine and resume normal execution.
</p>

<p>
A call to <code>recover</code> stops the unwinding and returns the
argument passed to <code>panic</code>.  Because the only code that
runs while unwinding is inside deferred functions, <code>recover</code>
is only useful inside deferred functions.
</p>

<p>
One application of <code>recover</code> is to shut down a failing goroutine
inside a server without killing the other executing goroutines.
</p>

<pre>
2871
func server(workChan &lt;-chan *Work) {
Rob Pike's avatar
Rob Pike committed
2872
    for work := range workChan {
2873
        go safelyDo(work)
Rob Pike's avatar
Rob Pike committed
2874 2875 2876 2877 2878 2879
    }
}

func safelyDo(work *Work) {
    defer func() {
        if err := recover(); err != nil {
2880
            log.Println("work failed:", err)
Rob Pike's avatar
Rob Pike committed
2881 2882 2883 2884 2885 2886 2887 2888 2889 2890 2891 2892 2893 2894
        }
    }()
    do(work)
}
</pre>

<p>
In this example, if <code>do(work)</code> panics, the result will be
logged and the goroutine will exit cleanly without disturbing the
others.  There's no need to do anything else in the deferred closure;
calling <code>recover</code> handles the condition completely.
</p>

<p>
2895 2896 2897 2898 2899 2900 2901 2902 2903 2904
Because <code>recover</code> always returns <code>nil</code> unless called directly
from a deferred function, deferred code can call library routines that themselves
use <code>panic</code> and <code>recover</code> without failing.  As an example,
the deferred function in <code>safelyDo</code> might call a logging function before
calling <code>recover</code>, and that logging code would run unaffected
by the panicking state.
</p>

<p>
With our recovery pattern in place, the <code>do</code>
Rob Pike's avatar
Rob Pike committed
2905 2906 2907 2908 2909
function (and anything it calls) can get out of any bad situation
cleanly by calling <code>panic</code>.  We can use that idea to
simplify error handling in complex software.  Let's look at an
idealized excerpt from the <code>regexp</code> package, which reports
parsing errors by calling <code>panic</code> with a local
2910
error type.  Here's the definition of <code>Error</code>,
Rob Pike's avatar
Rob Pike committed
2911 2912 2913 2914
an <code>error</code> method, and the <code>Compile</code> function.
</p>

<pre>
2915
// Error is the type of a parse error; it satisfies the error interface.
Rob Pike's avatar
Rob Pike committed
2916
type Error string
2917
func (e Error) Error() string {
Rob Pike's avatar
Rob Pike committed
2918 2919 2920 2921 2922 2923 2924 2925 2926 2927
    return string(e)
}

// error is a method of *Regexp that reports parsing errors by
// panicking with an Error.
func (regexp *Regexp) error(err string) {
    panic(Error(err))
}

// Compile returns a parsed representation of the regular expression.
2928
func Compile(str string) (regexp *Regexp, err error) {
Rob Pike's avatar
Rob Pike committed
2929 2930 2931 2932 2933 2934 2935 2936 2937 2938 2939 2940 2941 2942 2943 2944 2945
    regexp = new(Regexp)
    // doParse will panic if there is a parse error.
    defer func() {
        if e := recover(); e != nil {
            regexp = nil    // Clear return value.
            err = e.(Error) // Will re-panic if not a parse error.
        }
    }()
    return regexp.doParse(str), nil
}
</pre>

<p>
If <code>doParse</code> panics, the recovery block will set the
return value to <code>nil</code>&mdash;deferred functions can modify
named return values.  It then will then check, in the assignment
to <code>err</code>, that the problem was a parse error by asserting
2946
that it has the local type <code>Error</code>.
Rob Pike's avatar
Rob Pike committed
2947 2948 2949 2950 2951 2952 2953 2954 2955
If it does not, the type assertion will fail, causing a run-time error
that continues the stack unwinding as though nothing had interrupted
it.  This check means that if something unexpected happens, such
as an array index out of bounds, the code will fail even though we
are using <code>panic</code> and <code>recover</code> to handle
user-triggered errors.
</p>

<p>
2956
With error handling in place, the <code>error</code> method
Rob Pike's avatar
Rob Pike committed
2957 2958 2959 2960 2961 2962 2963
makes it easy to report parse errors without worrying about unwinding
the parse stack by hand.
</p>

<p>
Useful though this pattern is, it should be used only within a package.
<code>Parse</code> turns its internal <code>panic</code> calls into
2964
<code>error</code> values; it does not expose <code>panics</code>
Rob Pike's avatar
Rob Pike committed
2965
to its client.  That is a good rule to follow.
2966 2967
</p>

2968 2969 2970 2971 2972 2973 2974 2975 2976 2977 2978
<p>
By the way, this re-panic idiom changes the panic value if an actual
error occurs.  However, both the original and new failures will be
presented in the crash report, so the root cause of the problem will
still be visible.  Thus this simple re-panic approach is usually
sufficient&mdash;it's a crash after all&mdash;but if you want to
display only the original value, you can write a little more code to
filter unexpected problems and re-panic with the original error.
That's left as an exercise for the reader.
</p>

2979

2980 2981 2982 2983 2984 2985 2986 2987 2988 2989 2990 2991 2992 2993 2994 2995 2996 2997 2998 2999
<h2 id="web_server">A web server</h2>

<p>
Let's finish with a complete Go program, a web server.
This one is actually a kind of web re-server.
Google provides a service at
<a href="http://chart.apis.google.com">http://chart.apis.google.com</a>
that does automatic formatting of data into charts and graphs.
It's hard to use interactively, though,
because you need to put the data into the URL as a query.
The program here provides a nicer interface to one form of data: given a short piece of text,
it calls on the chart server to produce a QR code, a matrix of boxes that encode the
text.
That image can be grabbed with your cell phone's camera and interpreted as,
for instance, a URL, saving you typing the URL into the phone's tiny keyboard.
</p>
<p>
Here's the complete program.
An explanation follows.
</p>
3000 3001
<pre><!--{{code "progs/eff_qr.go"}}
-->package main
3002 3003

import (
3004 3005
    &#34;flag&#34;
    &#34;log&#34;
3006 3007
    &#34;net/http&#34;
    &#34;text/template&#34;
3008 3009
)

3010
var addr = flag.String(&#34;addr&#34;, &#34;:1718&#34;, &#34;http service address&#34;) // Q=17, R=18
3011 3012

var templ = template.Must(template.New(&#34;qr&#34;).Parse(templateStr))
3013 3014

func main() {
3015
    flag.Parse()
3016
    http.Handle(&#34;/&#34;, http.HandlerFunc(QR))
3017 3018
    err := http.ListenAndServe(*addr, nil)
    if err != nil {
3019
        log.Fatal(&#34;ListenAndServe:&#34;, err)
3020
    }
3021 3022
}

3023
func QR(w http.ResponseWriter, req *http.Request) {
3024
    templ.Execute(w, req.FormValue(&#34;s&#34;))
3025 3026 3027 3028 3029 3030 3031 3032
}

const templateStr = `
&lt;html&gt;
&lt;head&gt;
&lt;title&gt;QR Link Generator&lt;/title&gt;
&lt;/head&gt;
&lt;body&gt;
3033
{{if .}}
3034
&lt;img src=&#34;http://chart.apis.google.com/chart?chs=300x300&amp;cht=qr&amp;choe=UTF-8&amp;chl={{urlquery .}}&#34; /&gt;
3035
&lt;br&gt;
3036
{{html .}}
3037 3038
&lt;br&gt;
&lt;br&gt;
3039 3040 3041 3042
{{end}}
&lt;form action=&#34;/&#34; name=f method=&#34;GET&#34;&gt;&lt;input maxLength=1024 size=70
name=s value=&#34;&#34; title=&#34;Text to QR Encode&#34;&gt;&lt;input type=submit
value=&#34;Show QR&#34; name=qr&gt;
3043 3044 3045
&lt;/form&gt;
&lt;/body&gt;
&lt;/html&gt;
3046
`</pre>
3047 3048 3049 3050 3051 3052 3053 3054 3055 3056 3057 3058 3059 3060 3061
<p>
The pieces up to <code>main</code> should be easy to follow.
The one flag sets a default HTTP port for our server.  The template
variable <code>templ</code> is where the fun happens. It builds an HTML template
that will be executed by the server to display the page; more about
that in a moment.
</p>
<p>
The <code>main</code> function parses the flags and, using the mechanism
we talked about above, binds the function <code>QR</code> to the root path
for the server.  Then <code>http.ListenAndServe</code> is called to start the
server; it blocks while the server runs.
</p>
<p>
<code>QR</code> just receives the request, which contains form data, and
Russ Cox's avatar
Russ Cox committed
3062
executes the template on the data in the form value named <code>s</code>.
3063 3064
</p>
<p>
3065
The template package is powerful;
3066 3067 3068
this program just touches on its capabilities.
In essence, it rewrites a piece of text on the fly by substituting elements derived
from data items passed to <code>templ.Execute</code>, in this case the
Russ Cox's avatar
Russ Cox committed
3069
form value.  
3070
Within the template text (<code>templateStr</code>),
3071
double-brace-delimited pieces denote template actions.
3072
The piece from <code>{{if .}}</code>
Rob Pike's avatar
Rob Pike committed
3073
to <code>{{end}}</code> executes only if the value of the current data item, called <code>.</code> (dot),
3074 3075
is non-empty.
That is, when the string is empty, this piece of the template is suppressed.
3076 3077
</p>
<p>
Rob Pike's avatar
Rob Pike committed
3078
The snippet <code>{{urlquery .}}</code> says to process the data with the function
3079
<code>urlquery</code>, which sanitizes the query string
3080 3081 3082 3083 3084 3085 3086 3087 3088 3089 3090 3091 3092
for safe display on the web page.
</p>
<p>
The rest of the template string is just the HTML to show when the page loads.
If this is too quick an explanation, see the <a href="/pkg/template/">documentation</a>
for the template package for a more thorough discussion.
</p>
<p>
And there you have it: a useful webserver in a few lines of code plus some
data-driven HTML text.
Go is powerful enough to make a lot happen in a few lines.
</p>

Rob Pike's avatar
Rob Pike committed
3093
<!--
Rob Pike's avatar
Rob Pike committed
3094
TODO
3095 3096 3097 3098 3099 3100 3101 3102
<pre>
verifying implementation
type Color uint32
    
// Check that Color implements image.Color and image.Image
var _ image.Color = Black
var _ image.Image = Black
</pre>
Rob Pike's avatar
Rob Pike committed
3103
-->
Rob Pike's avatar
Rob Pike committed
3104