Skip to content

uber/h3-go

master
Switch branches/tags
Code

Latest commit

* fix: SetToLinkedGeo structure bug

* Update build.yml (#1)

* Update build.yml
6161fdb

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
v3
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

H3 Logo

Build Coverage Status License GoDoc H3 Version

H3-Go is looking for a maintainer familiar with Go, C, and H3. Volunteers welcome! Please get in touch with us on the H3 Slack.

H3-Go

This library provides Golang bindings for the H3 Core Library. For API reference, please see the H3 Documentation.

Usage

Prerequisites

H3-Go requires 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).

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.

Installation

golang/dep

dep ensure -add github.com/uber/h3-go

Note: h3-go includes non-go directories that, by default, dep will prune. You can prevent this by including the following prune directive in your Gopkg.toml:

[prune]
	[[prune.project]]
		name = "github.com/uber/h3-go"
		non-go = false
		unused-packages = false

golang/cmd/go

go get github.com/uber/h3-go

Glide

glide install github.com/uber/h3-go

Quickstart

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
}

Notes

API Differences

  • All GeoCoord structs return Latitude and Longitude as degrees, instead of radians.

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.

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.

Contributing

Pull requests and Github issues are welcome. Please read our contributing guide for more information.

Legal and Licensing

H3-Go is licensed under the Apache 2.0 License.