From f76bd4fe0f55b753481e5d20b52155090a22ab42 Mon Sep 17 00:00:00 2001 From: Rob Pike Date: Mon, 12 Dec 2011 19:25:25 -0800 Subject: [PATCH] doc/go1: more package updates Everything there (as first draft) except the time package. R=golang-dev, adg, bradfitz CC=golang-dev https://golang.org/cl/5487052 --- doc/go1.html | 119 +++++++++++++++++++++++++++++++++++++++++++++++++++ doc/go1.tmpl | 119 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 238 insertions(+) diff --git a/doc/go1.html b/doc/go1.html index dee680add6b..420cae4de13 100644 --- a/doc/go1.html +++ b/doc/go1.html @@ -626,8 +626,55 @@ rather than syscall and so will be unaffected.

Time

+

The html package

+ +

+The html package in Go 1 provides +a full parser for HTML5. +

+ +

+Updating: +Since the package's functionality is new, no updating is necessary. +

+

The http package

+

+In Go 1 the http package is refactored, +putting some of the utilities into a +httputil subdirectory. +These pieces are only rarely needed by HTTP clients. +The affected items are: +

+ + + +

+Also, the Request.RawURL field has been removed; it was a +historical artifact. +

+ +

+Updating: +Gofix will update the few programs that are affected except for +uses of RawURL, which must be fixed by hand. +

+

The strconv package

@@ -724,6 +771,78 @@ a cast that must be added by hand; gofix will warn about it.

The os.FileInfo type

+

+Go 1 redefines the os.FileInfo type, +changing it from a struct to an interface: +

+ +
+    type FileInfo interface {
+        Name() string       // base name of the file
+        Size() int64        // length in bytes
+        Mode() FileMode     // file mode bits
+        ModTime() time.Time // modification time
+        IsDir() bool        // abbreviation for Mode().IsDir()
+    }
+
+ +

+The file mode information has been moved into a subtype called +os.FileMode, +a simple integer type with IsDir, Perm, and String +methods. +

+ +

+The system-specific details of file modes and properties such as (on Unix) +i-number have been removed from FileInfo altogether. +Instead, each operating system's os package provides an +implementation of the FileInfo interface, *os.FileStat, +which in turn contains a Sys field that stores the +system-specific representation of file metadata. +For instance, to discover the i-number of a file on a Unix system, unpack +the FileInfo like this: +

+ +
+    fi, err := os.Stat("hello.go")
+    if err != nil {
+        log.Fatal(err)
+    }
+    // Make sure it's an implementation known to package os.
+    fileStat, ok := fi.(*os.FileStat)
+    if !ok {
+        log.Fatal("hello.go: not an os File")
+    }
+    // Now check that it's a Unix file.
+    unixStat, ok := fileStat.Sys.(*syscall.Stat_t)
+    if !ok {
+        log.Fatal("hello.go: not a Unix file")
+    }
+    fmt.Printf("file i-number: %d\n", unixStat.Ino)
+
+ +

+Assuming (which is unwise) that "hello.go" is a Unix file, +the i-number expression could be contracted to +

+ +
+    fi.(*os.FileStat).Sys.(*syscall.Stat_t).Ino
+
+ +

+The vast majority of uses of FileInfo need only the methods +of the standard interface. +

+ +

+Updating: +Gofix will update code that uses the old equivalent of the current os.FileInfo +and os.FileMode API. +Code that needs system-specific file details will need to be updated by hand. +

+

The package tree exp

diff --git a/doc/go1.tmpl b/doc/go1.tmpl index c830b3572ca..77eeebaf53d 100644 --- a/doc/go1.tmpl +++ b/doc/go1.tmpl @@ -529,8 +529,55 @@ rather than syscall and so will be unaffected.

Time

+

The html package

+ +

+The html package in Go 1 provides +a full parser for HTML5. +

+ +

+Updating: +Since the package's functionality is new, no updating is necessary. +

+

The http package

+

+In Go 1 the http package is refactored, +putting some of the utilities into a +httputil subdirectory. +These pieces are only rarely needed by HTTP clients. +The affected items are: +

+ + + +

+Also, the Request.RawURL field has been removed; it was a +historical artifact. +

+ +

+Updating: +Gofix will update the few programs that are affected except for +uses of RawURL, which must be fixed by hand. +

+

The strconv package

@@ -627,6 +674,78 @@ a cast that must be added by hand; gofix will warn about it.

The os.FileInfo type

+

+Go 1 redefines the os.FileInfo type, +changing it from a struct to an interface: +

+ +
+    type FileInfo interface {
+        Name() string       // base name of the file
+        Size() int64        // length in bytes
+        Mode() FileMode     // file mode bits
+        ModTime() time.Time // modification time
+        IsDir() bool        // abbreviation for Mode().IsDir()
+    }
+
+ +

+The file mode information has been moved into a subtype called +os.FileMode, +a simple integer type with IsDir, Perm, and String +methods. +

+ +

+The system-specific details of file modes and properties such as (on Unix) +i-number have been removed from FileInfo altogether. +Instead, each operating system's os package provides an +implementation of the FileInfo interface, *os.FileStat, +which in turn contains a Sys field that stores the +system-specific representation of file metadata. +For instance, to discover the i-number of a file on a Unix system, unpack +the FileInfo like this: +

+ +
+    fi, err := os.Stat("hello.go")
+    if err != nil {
+        log.Fatal(err)
+    }
+    // Make sure it's an implementation known to package os.
+    fileStat, ok := fi.(*os.FileStat)
+    if !ok {
+        log.Fatal("hello.go: not an os File")
+    }
+    // Now check that it's a Unix file.
+    unixStat, ok := fileStat.Sys.(*syscall.Stat_t)
+    if !ok {
+        log.Fatal("hello.go: not a Unix file")
+    }
+    fmt.Printf("file i-number: %d\n", unixStat.Ino)
+
+ +

+Assuming (which is unwise) that "hello.go" is a Unix file, +the i-number expression could be contracted to +

+ +
+    fi.(*os.FileStat).Sys.(*syscall.Stat_t).Ino
+
+ +

+The vast majority of uses of FileInfo need only the methods +of the standard interface. +

+ +

+Updating: +Gofix will update code that uses the old equivalent of the current os.FileInfo +and os.FileMode API. +Code that needs system-specific file details will need to be updated by hand. +

+

The package tree exp