V4 (#54)

uber · Aug 27, 2022 · 1665ba6 · 1665ba6
1 parent 6161fdb
commit 1665ba6
Show file tree

Hide file tree

Showing 95 changed files with 5,047 additions and 12,945 deletions.
diff --git a/.gitattributes b/.gitattributes
@@ -1,3 +1,3 @@
 # treat C source and header files as binary as they are script managed
-*.c binary
-*.h binary
+*.c binary linguist-generated
+*.h binary linguist-generated
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -2,31 +2,45 @@ name: Build
 
 on: [push, pull_request]
 
+permissions:
+  contents: read
+
 jobs:
-  build:
+  golangci:
+    name: lint
+    runs-on: ubuntu-latest
     strategy:
       matrix:
-        go-version: ['1.11', '1.12', '1.13', '1.14', '1.15']
+        go-version: ["1.18"]
+
+    steps:
+      - uses: actions/setup-go@v3
+        with:
+          go-version: ${{ matrix.go-version }}
+      - uses: actions/checkout@v3
+      - name: golangci-lint
+        uses: golangci/golangci-lint-action@v3
+        with:
+          version: v1.47.3
 
+  test:
+    name: test
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        go-version: ["1.18", "1.19"]
 
     steps:
-    - name: Setup Go ${{ matrix.go-version }}
-      uses: actions/setup-go@v2
-      with:
-        go-version: ${{ matrix.go-version }}
-    - uses: actions/checkout@v2
-    - name: go get
-      run: |
-        go get -t ./...
-    - name: Run Unit tests
-      run: |
-        go test -race -covermode atomic -coverprofile=covprofile ./...
-    - name: Install goveralls
-      #env:
-        #GO111MODULE: off
-      run: go get github.com/mattn/goveralls
-    - name: Send coverage
-      env:
-        COVERALLS_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      run: goveralls -coverprofile=covprofile -service=github
+      - uses: actions/setup-go@v3
+        with:
+          go-version: ${{ matrix.go-version }}
+      - uses: actions/checkout@v3
+      - name: unit-tests
+        run: |
+          go test -count=2 -race -covermode atomic -coverprofile=covprofile ./...
+      - name: goveralls
+        env:
+          COVERALLS_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          go install github.com/mattn/goveralls@latest
+          goveralls -coverprofile=covprofile -service=github
diff --git a/.golangci.yml b/.golangci.yml
@@ -0,0 +1,64 @@
+linters-settings:
+  errcheck:
+    check-type-assertions: true
+  goconst:
+    min-len: 2
+    min-occurrences: 3
+  gocritic:
+    enabled-tags:
+      - diagnostic
+      - experimental
+      - opinionated
+      - performance
+      - style
+  govet:
+    check-shadowing: true
+  nolintlint:
+    require-explanation: true
+    require-specific: true
+  wsl:
+    allow-assign-and-anything: true
+    allow-cuddle-declarations: true
+    allow-assign-and-call: true
+
+linters:
+  disable-all: true
+  enable:
+    - bodyclose
+    - deadcode
+    - depguard
+    - dogsled
+    - dupl
+    - errcheck
+    - exportloopref
+    - exhaustive
+    - goconst
+    # - gocritic
+    - gofmt
+    - goimports
+    - gomnd
+    - gocyclo
+    - gosec
+    - gosimple
+    - govet
+    - ineffassign
+    - misspell
+    - nolintlint
+    - nakedret
+    - prealloc
+    - predeclared
+    - revive
+    - staticcheck
+    - structcheck
+    - stylecheck
+    - thelper
+    - tparallel
+    - typecheck
+    - unconvert
+    - unparam
+    - varcheck
+    - whitespace
+    - wsl
+
+run:
+  issues-exit-code: 1
diff --git a/H3_VERSION b/H3_VERSION
@@ -1 +1 @@
-v3.4.0
+v4.0.0-rc4
diff --git a/README.md b/README.md
@@ -11,93 +11,130 @@
 # H3-Go
 
 This library provides Golang bindings for the
-[H3 Core Library](https://github.com/uber/h3). For API reference, please see the
+[H3 Core Library](https://github.com/uber/h3). For API reference, see the
 [H3 Documentation](https://uber.github.io/h3/).
 
-# Usage
-
-## Prerequisites
-
-H3-Go requires [CGO](https://golang.org/cmd/cgo/) (`CGO_ENABLED=1`) in order to be built.  Generally, Go should do the right thing when including this library:
-
-> The cgo tool is enabled by default for native builds on systems where it is expected to work. It is disabled by default when cross-compiling. You can control this by setting the CGO_ENABLED environment variable when running the go tool: set it to 1 to enable the use of cgo, and to 0 to disable it. The go tool will set the build constraint "cgo" if cgo is enabled. The special import "C" implies the "cgo" build constraint, as though the file also said "// +build cgo". Therefore, if cgo is disabled, files that import "C" will not be built by the go tool. (For more about build constraints see https://golang.org/pkg/go/build/#hdr-Build_Constraints).
+**This is v4 of this library, supporting H3 v4.**
 
-If you see errors/warnings like _"build constraints exclude all Go files..."_, then the `cgo` build constraint is likely disabled; try setting `CGO_ENABLED=1` environment variable for your build step.
+Check out [v3](https://github.com/uber/h3-go/tree/v3.7.1) or checkout the git tag for the version you need.
 
-## Installation
+**Migrating from v3?**
 
-### [golang/dep](https://github.com/golang/dep)
+Check out [v3 to v4 migration guide](https://h3geo.org/docs/next/library/migrating-3.x/).
+There have been no breaking changes to the format of H3 indexes.  Indexes
+generated by older versions can be parsed in v4, and vice-versa.
 
-```bash
-dep ensure -add github.com/uber/h3-go
-```
+# Usage
 
-Note: h3-go includes non-go directories that, by default, `dep` will
-[prune](https://golang.github.io/dep/docs/Gopkg.toml.html#prune).  You can
-prevent this by including the following prune directive in your `Gopkg.toml`:
+## Prerequisites
 
-```toml
-[prune]
-	[[prune.project]]
-		name = "github.com/uber/h3-go"
-		non-go = false
-		unused-packages = false
-```
+H3-Go requires [CGO](https://golang.org/cmd/cgo/) (`CGO_ENABLED=1`) in order to
+be built. Go should do the right thing when including this library:
 
-### [golang/cmd/go](https://golang.org/cmd/go/)
+> The cgo tool is enabled by default for native builds on systems where it is
+> expected to work. It is disabled by default when cross-compiling. You can
+> control this by setting the CGO_ENABLED environment variable when running the go
+> tool: set it to 1 to enable the use of cgo, and to 0 to disable it. The go tool
+> will set the build constraint "cgo" if cgo is enabled. The special import "C"
+> implies the "cgo" build constraint, as though the file also said "// +build
+> cgo". Therefore, if cgo is disabled, files that import "C" will not be built by
+> the go tool. (For more about build constraints see
+> https://golang.org/pkg/go/build/#hdr-Build_Constraints).
 
-```bash
-go get github.com/uber/h3-go
-```
+If you see errors/warnings like _"build constraints exclude all Go files..."_,
+then the `cgo` build constraint is likely disabled; try setting `CGO_ENABLED=1`
+environment variable in your `go build` step.
 
-### [Glide](https://github.com/Masterminds/glide)
+## Installation
 
 ```bash
-glide install github.com/uber/h3-go
+go get github.com/uber/h3-go/v4
 ```
 
 ## Quickstart
 
 ```go
-import "github.com/uber/h3-go/v3"
-
-func ExampleFromGeo() {
-	geo := h3.GeoCoord{
-		Latitude:  37.775938728915946,
-		Longitude: -122.41795063018799,
-	}
-	resolution := 9
-	fmt.Printf("%#x\n", h3.FromGeo(geo, resolution))
-	// Output:
-	// 0x8928308280fffff
-}
-```
+import "github.com/uber/h3-go/v4"
 
-# Notes
+func ExampleLatLngToCell() {
+	latLng := h3.NewLatLng(37.775938728915946, -122.41795063018799)
+	resolution := 9 // between 0 (biggest cell) and 15 (smallest cell)
 
-## API Differences
+	cell := h3.LatLngToCell(latLng, resolution)
 
-* All `GeoCoord` structs return `Latitude` and `Longitude` as degrees, instead
-  of radians.
+	fmt.Printf("%s", cell) 
+	// Output:
+	// 8928308280fffff
+}
 
-Some superficial changes have been made relative to the H3 C core API in order
-to adhere to idiomatic Go styling.  Most notable are the following:
+```
 
-* H3 C API function prefixes of `H3` have been dropped to reduce stutter in
-  usage, e.g. `h3.ToGeo(h)`.
-* H3 C functions that convert **to** `H3Index` have their names inverted to
-  convert **from** something else to `H3Index`, e.g. `GeoToH3` is renamed to
-  `h3.FromGeo`.
-* H3 C API function prefixes of `Get` have been dropped in support of Golang's
-  `Getter` [naming style](https://golang.org/doc/effective_go.html#Getters).
+# C API 
+
+## Notes
+* `LatLng` returns `Lat` and `Lng` as degrees, instead of radians.
+* H3 C API function prefixes of `get` have been dropped in support of Golang's
+ `Getter` [naming style](https://golang.org/doc/effective_go.html#Getters).
+* Convenience methods have been added to various types where that type was the
+  main or only argument.
+
+## Bindings
+
+| C API                        | Go API                                             |
+| ---------------------------- | -------------------------------------------------- |
+| `latLngToCell`               | `LatLngToCell`, `LatLng#Cell`                      |
+| `cellToLatLng`               | `CellToLatLng`, `Cell#LatLng`                      |
+| `cellToBoundary`             | `CellToBoundary`, `Cell#Boundary`                  |
+| `gridDisk`                   | `GridDisk`, `Cell#GridDisk`                        |
+| `gridDiskDistances`          | `GridDiskDistances`, `Cell#GridDiskDistances`      |
+| `gridRingUnsafe`             | N/A                                                |
+| `polygonToCells`             | `PolygonToCells`, `GeoPolygon#Cells`               |
+| `cellsToMultiPolygon`        | TODO                                               |
+| `degsToRads`                 | `DegsToRads`                                       |
+| `radsToDegs`                 | `RadsToDegs`                                       |
+| `greatCircleDistance`        | `GreatCircleDistance* (3/3)`                       |
+| `getHexagonAreaAvg`          | `HexagonAreaAvg* (3/3)`                            |
+| `cellArea`                   | `CellArea* (3/3)`                                  |
+| `getHexagonEdgeLengthAvg`    | `HexagonEdgeLengthAvg* (2/2)`                      |
+| `exactEdgeLength`            | `ExactEdgeLength* (3/3)`                           |
+| `getNumCells`                | `NumCells`                                         |
+| `getRes0Cells`               | `Res0Cells`                                        |
+| `getPentagons`               | `Pentagons`                                        |
+| `getResolution`              | `Resolution`                                       |
+| `getBaseCellNumber`          | `BaseCellNumber`, `Cell#BaseCellNumber`            |
+| `stringToH3`                 | `IndexFromString`, `Cell#UnmarshalText`            |
+| `h3ToString`                 | `IndexToString`, `Cell#String`, `Cell#MarshalText` |
+| `isValidCell`                | `Cell#IsValid`                                     |
+| `cellToParent`               | `Cell#Parent`, `Cell#ImmediateParent`              |
+| `cellToChildren`             | `Cell#Children` `Cell#ImmediateChildren`           |
+| `cellToCenterChild`          | `Cell#CenterChild`                                 |
+| `compactCells`               | `CompactCells`                                     |
+| `uncompactCells`             | `UncompactCells`                                   |
+| `isResClassIII`              | `Cell#IsResClassIII`                               |
+| `isPentagon`                 | `Cell#IsPentagon`                                  |
+| `getIcosahedronFaces`        | `Cell#IcosahedronFaces`                            |
+| `areNeighborCells`           | `Cell#IsNeighbor`                                  |
+| `cellsToDirectedEdge`        | `Cell#DirectedEdge`                                |
+| `isValidDirectedEdge`        | `DirectedEdge#IsValid`                             |
+| `getDirectedEdgeOrigin`      | `DirectedEdge#Origin`                              |
+| `getDirectedEdgeDestination` | `DirectedEdge#Destination`                         |
+| `directedEdgeToCells`        | `DirectedEdge#Cells`                               |
+| `originToDirectedEdges`      | `Cell#DirectedEdges`                               |
+| `directedEdgeToBoundary`     | `DirectedEdge#Boundary`                            |
+| `cellToVertex`               | TODO                                               |
+| `cellToVertexes`             | TODO                                               |
+| `vertexToLatLng`             | TODO                                               |
+| `isValidVertex`              | TODO                                               |
+| `gridDistance`               | `GridDistance`, `Cell#GridDistance`                |
+| `gridPathCells`              | `GridPath`, `Cell#GridPath`                        |
+| `cellToLocalIj`              | `CellToLocalIJ`                                    |
+| `localIjToCell`              | `LocalIJToCell`                                    |
 
 ## CGO
 
 The H3 C source code and header files are copied into this project to optimize
-for portability.  By including the C source files in the `h3` Go package, there
-is no need to introduce a build process or a system dependency on an H3 binary.
-Effectively, this decision makes `h3` as easy to use in a Go project as adding
-it as a dependency with your favorite dependency manager.
+for portability. `h3-go` can be imported into any Go project for any platform
+that CGO supports.
 
 # Contributing