save

Author: jcbhmr

content/en/docs/README.md

@@ -0,0 +1,52 @@
+[Go](https://go.dev/) is an open-source programming language designed for building scalable, secure, and reliable software. Please read the [official documentation](https://go.dev/doc/tutorial/getting-started) to learn more.
+
+*Go by Example* is a hands-on introduction to Go using annotated example programs. Check out the [first example](hello-world.md) or browse the full list below.
+
+Unless stated otherwise, the examples here assume the [latest major release Go](https://go.dev/doc/devel/release) and may use new language features. If something isn't working, try upgrading to the latest version.
+
+<br>
+
+<style>
+/* Make draft links from included SUMMARY.md on README.md non-clickable. */
+#content a[href=""] {
+    color: var(--sidebar-non-existant);;
+    text-decoration: none;
+    cursor: default;
+    pointer-events: none;
+}
+</style>
+
+{{#include SUMMARY.md:7:}}
+
+### FAQ
+
+#### I found a problem with the examples; what do I do?
+
+We're very happy to fix problem reports and accept contributions! Please submit
+[an issue](https://github.com/jcbhmt/gobyexample.jcbhmr.com/issues) or send a Pull Request.
+See `CONTRIBUTING.md` for more details.
+
+#### What version of Go is required to run these examples?
+
+Given Go's strong [backwards compatibility guarantees](https://go.dev/doc/go1compat),
+we expect the vast majority of examples to work on the latest released version of Go
+as well as many older releases going back years.
+
+That said, some examples show off new features added in recent releases; therefore,
+it's recommended to try running examples with the latest officially released Go version
+(see Go's [release history](https://go.dev/doc/devel/release) for details).
+
+#### I'm getting output in a different order from the example. Is the example wrong?
+
+Some of the examples demonstrate concurrent code which has a non-deterministic
+execution order. It depends on how the Go runtime schedules its goroutines and
+may vary by operating system, CPU architecture, or even Go version.
+
+Similarly, examples that iterate over maps may produce items in a different order
+from what you're getting on your machine. This is because the order of iteration
+over maps in Go is [not specified and is not guaranteed to be the same from one
+iteration to the next](https://go.dev/ref/spec#RangeClause).
+
+It doesn't mean anything is wrong with the example. Typically the code in these
+examples will be insensitive to the actual order of the output; if the code is
+sensitive to the order - that's probably a bug - so feel free to report it.

content/en/docs/for.md

@@ -0,0 +1,69 @@
+# For
+
+```go,editable
+// `for` is Go's only looping construct. Here are
+// some basic types of `for` loops.
+
+package main
+
+import "fmt"
+
+func main() {
+
+	// The most basic type, with a single condition.
+	i := 1
+	for i <= 3 {
+		fmt.Println(i)
+		i = i + 1
+	}
+
+	// A classic initial/condition/after `for` loop.
+	for j := 0; j < 3; j++ {
+		fmt.Println(j)
+	}
+
+	// Another way of accomplishing the basic "do this
+	// N times" iteration is `range` over an integer.
+	for i := range 3 {
+		fmt.Println("range", i)
+	}
+
+	// `for` without a condition will loop repeatedly
+	// until you `break` out of the loop or `return` from
+	// the enclosing function.
+	for {
+		fmt.Println("loop")
+		break
+	}
+
+	// You can also `continue` to the next iteration of
+	// the loop.
+	for n := range 6 {
+		if n%2 == 0 {
+			continue
+		}
+		fmt.Println(n)
+	}
+}
+```
+
+```sh
+$ go run for.go
+1
+2
+3
+0
+1
+2
+range 0
+range 1
+range 2
+loop
+1
+3
+5
+
+# We'll see some other `for` forms later when we look at
+# `range` statements, channels, and other data
+# structures.
+```

content/en/docs/functions.md

@@ -0,0 +1,48 @@
+# Functions
+
+```go,editable
+// _Functions_ are central in Go. We'll learn about
+// functions with a few different examples.
+
+package main
+
+import "fmt"
+
+// Here's a function that takes two `int`s and returns
+// their sum as an `int`.
+func plus(a int, b int) int {
+
+	// Go requires explicit returns, i.e. it won't
+	// automatically return the value of the last
+	// expression.
+	return a + b
+}
+
+// When you have multiple consecutive parameters of
+// the same type, you may omit the type name for the
+// like-typed parameters up to the final parameter that
+// declares the type.
+func plusPlus(a, b, c int) int {
+	return a + b + c
+}
+
+func main() {
+
+	// Call a function just as you'd expect, with
+	// `name(args)`.
+	res := plus(1, 2)
+	fmt.Println("1+2 =", res)
+
+	res = plusPlus(1, 2, 3)
+	fmt.Println("1+2+3 =", res)
+}
+```
+
+```sh
+$ go run functions.go
+1+2 = 3
+1+2+3 = 6
+
+# There are several other features to Go functions. One is
+# multiple return values, which we'll look at next.
+```

content/en/docs/generics.md

@@ -0,0 +1,89 @@
+# Generics
+
+```go,editable
+// Starting with version 1.18, Go has added support for
+// _generics_, also known as _type parameters_.
+
+package main
+
+import "fmt"
+
+// As an example of a generic function, `SlicesIndex` takes
+// a slice of any `comparable` type and an element of that
+// type and returns the index of the first occurrence of
+// v in s, or -1 if not present. The `comparable` constraint
+// means that we can compare values of this type with the
+// `==` and `!=` operators. For a more thorough explanation
+// of this type signature, see [this blog post](https://go.dev/blog/deconstructing-type-parameters).
+// Note that this function exists in the standard library
+// as [slices.Index](https://pkg.go.dev/slices#Index).
+func SlicesIndex[S ~[]E, E comparable](s S, v E) int {
+	for i := range s {
+		if v == s[i] {
+			return i
+		}
+	}
+	return -1
+}
+
+// As an example of a generic type, `List` is a
+// singly-linked list with values of any type.
+type List[T any] struct {
+	head, tail *element[T]
+}
+
+type element[T any] struct {
+	next *element[T]
+	val  T
+}
+
+// We can define methods on generic types just like we
+// do on regular types, but we have to keep the type
+// parameters in place. The type is `List[T]`, not `List`.
+func (lst *List[T]) Push(v T) {
+	if lst.tail == nil {
+		lst.head = &element[T]{val: v}
+		lst.tail = lst.head
+	} else {
+		lst.tail.next = &element[T]{val: v}
+		lst.tail = lst.tail.next
+	}
+}
+
+// AllElements returns all the List elements as a slice.
+// In the next example we'll see a more idiomatic way
+// of iterating over all elements of custom types.
+func (lst *List[T]) AllElements() []T {
+	var elems []T
+	for e := lst.head; e != nil; e = e.next {
+		elems = append(elems, e.val)
+	}
+	return elems
+}
+
+func main() {
+	var s = []string{"foo", "bar", "zoo"}
+
+	// When invoking generic functions, we can often rely
+	// on _type inference_. Note that we don't have to
+	// specify the types for `S` and `E` when
+	// calling `SlicesIndex` - the compiler infers them
+	// automatically.
+	fmt.Println("index of zoo:", SlicesIndex(s, "zoo"))
+
+	// ... though we could also specify them explicitly.
+	_ = SlicesIndex[[]string, string](s, "zoo")
+
+	lst := List[int]{}
+	lst.Push(10)
+	lst.Push(13)
+	lst.Push(23)
+	fmt.Println("list:", lst.AllElements())
+}
+```
+
+```sh
+$ go run generics.go
+index of zoo: 2
+list: [10 13 23]
+```

content/en/docs/goroutines.md

@@ -0,0 +1,63 @@
+# Goroutines
+
+```go,editable
+// A _goroutine_ is a lightweight thread of execution.
+
+package main
+
+import (
+	"fmt"
+	"time"
+)
+
+func f(from string) {
+	for i := 0; i < 3; i++ {
+		fmt.Println(from, ":", i)
+	}
+}
+
+func main() {
+
+	// Suppose we have a function call `f(s)`. Here's how
+	// we'd call that in the usual way, running it
+	// synchronously.
+	f("direct")
+
+	// To invoke this function in a goroutine, use
+	// `go f(s)`. This new goroutine will execute
+	// concurrently with the calling one.
+	go f("goroutine")
+
+	// You can also start a goroutine for an anonymous
+	// function call.
+	go func(msg string) {
+		fmt.Println(msg)
+	}("going")
+
+	// Our two function calls are running asynchronously in
+	// separate goroutines now. Wait for them to finish
+	// (for a more robust approach, use a [WaitGroup](waitgroups)).
+	time.Sleep(time.Second)
+	fmt.Println("done")
+}
+```
+
+```sh
+# When we run this program, we see the output of the
+# blocking call first, then the output of the two
+# goroutines. The goroutines' output may be interleaved,
+# because goroutines are being run concurrently by the
+# Go runtime.
+$ go run goroutines.go
+direct : 0
+direct : 1
+direct : 2
+goroutine : 0
+going
+goroutine : 1
+goroutine : 2
+done
+
+# Next we'll look at a complement to goroutines in
+# concurrent Go programs: channels.
+```

content/en/docs/hello-world.md

@@ -0,0 +1,33 @@
+# Hello World
+
+```go,editable
+// Our first program will print the classic "hello world"
+// message. Here's the full source code.
+package main
+
+import "fmt"
+
+func main() {
+	fmt.Println("hello world")
+}
+```
+
+```sh
+# To run the program, put the code in `hello-world.go` and
+# use `go run`.
+$ go run hello-world.go
+hello world
+
+# Sometimes we'll want to build our programs into
+# binaries. We can do this using `go build`.
+$ go build hello-world.go
+$ ls
+hello-world	hello-world.go
+
+# We can then execute the built binary directly.
+$ ./hello-world
+hello world
+
+# Now that we can run and build basic Go programs, let's
+# learn more about the language.
+```