A small, powerful and flexible merge library.

<img align="right" src="images/gopher-merge.png">

# conjungo

[![LICENSE](https://img.shields.io/badge/license-MIT-orange.svg)](LICENSE)
[![Golang](https://img.shields.io/badge/Golang-v1.7-blue.svg)](https://golang.org/dl/)
[![Godocs](https://img.shields.io/badge/golang-documentation-blue.svg)](https://godoc.org/github.com/InVisionApp/conjungo)
[![Go Report Card](https://goreportcard.com/badge/github.com/InVisionApp/conjungo)](https://goreportcard.com/report/github.com/InVisionApp/conjungo)
[![Travis Build Status](https://travis-ci.com/InVisionApp/conjungo.svg?token=KosA43m1X3ikri8JEukQ&branch=master)](https://travis-ci.com/InVisionApp/conjungo) 
[![codecov](https://codecov.io/gh/InVisionApp/conjungo/branch/master/graph/badge.svg?token=lesB1PUEtL)](https://codecov.io/gh/InVisionApp/conjungo)

A merge utility designed for flexibility and customizability. The library has a
single simple point of entry that works out of the box for most basic use cases. 
From there, customizations can be made to the way two items are merged to fit 
your specific needs.

Merge any two things of the same type, including maps, slices, structs, and even 
basic types like string and int. By default, the target value will be overwritten 
by the source. If the overwrite option is turned off, only new values in source 
that do not already exist in target will be added.  

If you would like to change the way two items of a particular type get merged,
custom merge functions can be defined for any type or kind (see below).  

## Why Conjungo?

The definition of Conjungo:  
> I.v. a., to bind together, connect, join, unite (very freq. in all perr. and species of composition); constr. with cum, inter se, the dat., or the acc. only; trop. also with ad.

Reference: [Latin Dictionary...](http://www.perseus.tufts.edu/hopper/text?doc=Perseus:text:1999.04.0059:entry=conjungo)

There are other merge libraries written in go, but none of them have the 
flexibility of this one. If you simply need to merge two things, a default 
set of merge functions are defined for merging maps, slices, and structs like 
most other libraries. But, if the way these default functions are defined does 
not meet your needs, Conjungo provides the ability to define your own merge 
functions. For instance, the default behavior when merging two integers is to 
replace the target with the source, but if you'd like to redefine that, you 
can write a custom merge function that is used when assessing integers. A custom 
function could add the two integers and return the result, or return the larger 
of the two integers. You could define a custom merge function for a specific struct 
type in your code, and define how that gets merged. The customizability of how 
things get merged is the focus of Conjungo. 

The need for this library arose when we were merging large custom structs. We 
found that there was no single library that merged all the parts of the struct 
in the way that we needed. We had struct fields that were pointers to sub structs 
and maps that needed to be followed instead of simply replaced. We had slices 
that needed to be appended but also deduped. Conjungo solves these types of 
problems by allowing custom functions to be defined to handle each type.

## Setup
To get **conjungo**:
```sh
go get github.com/InVisionApp/conjungo
```

We recommend that you vendor it within your project. We chose to use govendor.

```sh 
govendor fetch github.com/InVisionApp/conjungo
```

## Usage
### Simple Merge
Merge two structs together:
```go
type Foo struct {
	Name    string
	Size    int
	Special bool
	SubMap  map[string]string
}

targetStruct := Foo{
	Name:    "target",
	Size:    2,
	Special: false,
	SubMap:  map[string]string{"foo": "unchanged", "bar": "orig"},
}

sourceStruct := Foo{
	Name:    "source",
	Size:    4,
	Special: true,
	SubMap:  map[string]string{"bar": "newVal", "safe": "added"},
}

err := conjungo.Merge(&targetStruct, sourceStruct, nil)
if err != nil {
	log.Error(err)
}
```
results in:
```json
{
  "Name": "source",
  "Size": 4,
  "Special": true,
  "SubMap": {
    "bar": "newVal",
    "foo": "unchanged",
    "safe": "added"
  }
}
```

### Options
**Overwrite** `bool`  
If true, overwrite a target value with source value even if it already exists

**ErrorOnUnexported** `bool`  
Unexported fields on a struct can not be set. When a struct contains an unexported
field, the default behavior is to treat the entire struct as a single entity and
replace according to Overwrite settings.  
If this is enabled, an error will be thrown instead.

### Custom Merge Functions
#### Define a custom merge function for a type:
```go
opts := conjungo.NewOptions()
opts.MergeFuncs.SetTypeMergeFunc(
	reflect.TypeOf(0),
	// merge two 'int' types by adding them together
	func(t, s reflect.Value, o *conjungo.Options) (reflect.Value, error) {
		iT, _ := t.Interface().(int)
		iS, _ := s.Interface().(int)
		return reflect.ValueOf(iT + iS), nil
	},
)

x := 1
y := 2

err := conjungo.Merge(&x, y, opts)
if err != nil {
	log.Error(err)
}

// x == 3
```

#### Define a custom merge function for a kind:
```go
opts := conjungo.NewOptions()
opts.MergeFuncs.SetKindMergeFunc(
	reflect.TypeOf(struct{}{}).Kind(),
	// merge two 'struct' kinds by replacing the target with the source
	// provides a mechanism to set override = true for just structs
	func(t, s reflect.Value, o *conjungo.Options) (reflect.Value, error) {
		return s, nil
	},
)
```

#### Define a custom merge function for a struct type:
```go
	type Foo struct {
		Name string
		Size int
	}

	target := Foo{
		Name: "bar",
		Size: 25,
	}

	source := Foo{
		Name: "baz",
		Size: 35,
	}

	opts := conjungo.NewOptions()
	opts.MergeFuncs.SetTypeMergeFunc(
		reflect.TypeOf(Foo{}),
		// merge two 'int' types by adding them together
		func(t, s reflect.Value, o *conjungo.Options) (reflect.Value, error) {
			tFoo := t.Interface().(Foo)
			sFoo := s.Interface().(Foo)

			// names are merged by concatenating them
			tFoo.Name = tFoo.Name + "." + sFoo.Name
			// sizes are merged by averaging them
			tFoo.Size = (tFoo.Size + sFoo.Size) / 2

			return reflect.ValueOf(tFoo), nil
		},
	)
```

#### Define a custom type and a function to merge it:
```go
type jsonString string

var targetJSON jsonString = `
{
  "a": "wrong",
  "b": 1,
  "c": {"bar": "orig", "foo": "unchanged"},
}`

var sourceJSON jsonString = `
{
  "a": "correct",
  "b": 2,
  "c": {"bar": "newVal", "safe": "added"},
}`

opts := conjungo.NewOptions()
opts.MergeFuncs.SetTypeMergeFunc(
	reflect.TypeOf(jsonString("")),
	// merge two json strings by unmarshalling them to maps
	func(t, s reflect.Value, o *conjungo.Options) (reflect.Value, error) {
		targetStr, _ := t.Interface().(jsonString)
		sourceStr, _ := s.Interface().(jsonString)

		targetMap := map[string]interface{}{}
		if err := json.Unmarshal([]byte(targetStr), &targetMap); err != nil {
			return reflect.Value{}, err
		}

		sourceMap := map[string]interface{}{}
		if err := json.Unmarshal([]byte(sourceStr), &sourceMap); err != nil {
			return reflect.Value{}, err
		}

		err := conjungo.Merge(&targetMap, sourceMap, o)
		if err != nil {
			return reflect.Value{}, err
		}

		mergedJSON, err := json.Marshal(targetMap)
		if err != nil {
			return reflect.Value{}, err
		}

		return reflect.ValueOf(jsonString(mergedJSON)), nil
	},
)
```

See [working examples](_example/main.go) for more details.


conjungo

Go package for mapping values to and from space-filling curves, such as Hilbert and Peano curves.

# Hilbert [![Build Status](https://img.shields.io/travis/google/hilbert.svg)](https://travis-ci.org/google/hilbert) [![Coverage](https://img.shields.io/coveralls/google/hilbert.svg)](https://coveralls.io/github/google/hilbert) [![Report card](https://goreportcard.com/badge/github.com/google/hilbert)](https://goreportcard.com/report/github.com/google/hilbert) [![GoDoc](https://godoc.org/github.com/google/hilbert?status.svg)](https://godoc.org/github.com/google/hilbert) [![Libraries.io](https://img.shields.io/librariesio/github/google/hilbert.svg)](https://libraries.io/github/google/hilbert)


Go package for mapping values to and from space-filling curves, such as
[Hilbert](https://en.wikipedia.org/wiki/Hilbert_curve) and [Peano](https://en.wikipedia.org/wiki/Peano_curve) curves.

![Image of 8 by 8 Hilbert curve](images/hilbert.png)

[Documentation available here](https://godoc.org/github.com/google/hilbert)

*This is not an official Google product (experimental or otherwise), it is just code that happens to be owned by Google.*
 
## How to use

Install:

```bash
go get github.com/google/hilbert
```

Example:

```go
import "github.com/google/hilbert"
	
// Create a Hilbert curve for mapping to and from a 16 by 16 space.
s, err := hilbert.NewHilbert(16)

// Create a Peano curve for mapping to and from a 27 by 27 space.
//s, err := hilbert.NewPeano(27)

// Now map one dimension numbers in the range [0, N*N-1], to an x,y
// coordinate on the curve where both x and y are in the range [0, N-1].
x, y, err := s.Map(t)

// Also map back from (x,y) to t.
t, err := s.MapInverse(x, y)
```

## Demo

The demo directory contains an example on how to draw an images of Hilbert and Peano curves, as well
as animations of varying sizes for both.

```bash
go run $GOPATH/src/github.com/google/hilbert/demo/demo.go
```

and the following images are generated. 

Simple 8x8 Hibert curve:

![8x8 Hilbert curve image](images/hilbert.png)

Simple 9x9 Peano curve:

![9x9 Hilbert curve image](images/peano.png)

Animation of Hibert curve with N in the range 1..8:

![Hilbert curve animation](images/hilbert_animation.gif)

Animation of Peano curve with N in the range 1..6:

![Peano curve animation](images/peano_animation.gif)

## Licence (Apache 2)

```
Copyright 2015 Google Inc. All Rights Reserved.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
```


hilbert

Functions that operate on slices; like `package strings` but adapted to work with slices.

# Slices
[![PkgGoDev](https://pkg.go.dev/badge/github.com/srfrog/slices)](https://pkg.go.dev/github.com/srfrog/slices)
[![Go Report Card](https://goreportcard.com/badge/github.com/srfrog/slices?svg=1)](https://goreportcard.com/report/github.com/srfrog/slices)
[![codecov](https://codecov.io/gh/srfrog/slices/branch/master/graph/badge.svg?token=IDUWTIYYZQ)](https://codecov.io/gh/srfrog/slices)
![Build Status](https://github.com/srfrog/slices/workflows/Go/badge.svg)

*Functions that operate on slices. Similar to functions from `package strings` or `package bytes` that have been adapted to work with slices.*

## Features

- [x] Using a thin layer of idiomatic Go; correctness over performance.
- [x] Provide most basic slice operations: index, trim, filter, map
- [x] Some PHP favorites like: pop, push, shift, unshift, shuffle, etc...
- [x] Non-destructive returns (won't alter original slice), except for explicit tasks.

## Quick Start

Install using "go get":

```bash
go get github.com/srfrog/slices
```

Then import from your source:

```
import "github.com/srfrog/slices"
```

View [example_test.go][1] for examples of basic usage and features.

## Documentation

The full code documentation is located at GoDoc:

[http://godoc.org/github.com/srfrog/slices](http://godoc.org/github.com/srfrog/slices)

## Usage

This is a en example showing basic usage.

```go
package main

import(
   "fmt"

   "github.com/srfrog/slices"
)

func main() {
	str := `Don't communicate by sharing memory - share memory by communicating`

	// Split string by spaces into a slice.
	slc := strings.Split(str, " ")

	// Count the number of "memory" strings in slc.
	memories := slices.Count(slc, "memory")
	fmt.Println("Memories:", memories)

	// Split slice into two parts.
	parts := slices.Split(slc, "-")
	fmt.Println("Split:", parts, len(parts))

	// Compare second parts slice with original slc.
	diff := slices.Diff(slc, parts[1])
	fmt.Println("Diff:", diff)

	// Chunk the slice
	chunks := slices.Chunk(parts[0], 1)
	fmt.Println("Chunk:", chunks)

	// Merge the parts
	merge := slices.Merge(chunks...)
	fmt.Println("Merge:", merge)
}
```

[1]: https://github.com/srfrog/slices/blob/master/example_test.go


slices

Persistent, fast ordered map using tree heaps.

# treap

[![Status](https://travis-ci.com/perdata/treap.svg?branch=master)](https://travis-ci.com/perdata/treap?branch=master)
[![GoDoc](https://godoc.org/github.com/perdata/treap?status.svg)](https://godoc.org/github.com/perdata/treap)
[![codecov](https://codecov.io/gh/perdata/treap/branch/master/graph/badge.svg)](https://codecov.io/gh/perdata/treap)
[![GoReportCard](https://goreportcard.com/badge/github.com/perdata/treap)](https://goreportcard.com/report/github.com/perdata/treap)

Package treap implements an immutabe sorted set datastructure using a combination tree/heap or [treap](https://en.wikipedia.org/wiki/Treap).

The algorithms are mostly based on [Fast Set Operations Using Treaps](https://www.cs.cmu.edu/~scandal/papers/treaps-spaa98.pdf)

Although the package is oriented towards ordered sets, it is simple to convert it to work as a persistent map.  There is a working [example](https://godoc.org/github.com/perdata/treap#example-package--OrderedMap) showing how to do this.


##  Benchmark stats

The most interesting benchmark is the performance of insert where a
single random key is inserted into a 5k sized map.  As the example
shows, the treap structure does well here as opposed to a regular
immutable map (using full copying).  This benchmark does not
take into account the fact that the regular maps are not sorted unlike
treaps. 

The intersection benchmark compares the case where two 10k sets with
5k in common being interesected. The regular map is about
30% faster but this is still respectable showing for treaps. 


```sh
$ go test --bench=. -benchmem
goos: darwin
goarch: amd64
pkg: github.com/perdata/treap
BenchmarkInsert-4                   	 1000000	      2347 ns/op	    1719 B/op	      36 allocs/op
BenchmarkInsertRegularMap-4         	    2000	    890745 ns/op	  336311 B/op	       8 allocs/op
BenchmarkIntersection-4             	     500	   3125772 ns/op	 1719838 B/op	   35836 allocs/op
BenchmarkIntersectionRegularMap-4   	     500	   2436519 ns/op	  718142 B/op	     123 allocs/op
BenchmarkUnion-4                    	    1000	   1451047 ns/op	  939846 B/op	   19580 allocs/op
BenchmarkDiff-4                     	     500	   3280823 ns/op	 1742080 B/op	   36298 allocs/op
PASS
```


The Best Go Libraries For Data Structures and Algorithms - Frameworks for performing ELT / ETL (4)

conjungo

hilbert

slices

treap