lancet

CategoryText Processing
SubcategoryUtility/Miscellaneous
Stars5,296
GitHubhttps://github.com/duke-git/lancet
A comprehensive, Lodash-like utility library for Go
About lancet

This large README is shown as a plain-text preview. Read the full README at the source
<div align=center>
<img src="./logo.png" width="200" height="200"/>

<br/>

![Go version](https://img.shields.io/badge/go-%3E%3Dv1.18-9cf)
[![Release](https://img.shields.io/badge/release-2.3.9-green.svg)](https://github.com/duke-git/lancet/releases)
[![GoDoc](https://godoc.org/github.com/duke-git/lancet/v2?status.svg)](https://pkg.go.dev/github.com/duke-git/lancet/v2)
[![Go Report Card](https://goreportcard.com/badge/github.com/duke-git/lancet/v2)](https://goreportcard.com/report/github.com/duke-git/lancet/v2)
[![test](https://github.com/duke-git/lancet/actions/workflows/codecov.yml/badge.svg?branch=main&event=push)](https://github.com/duke-git/lancet/actions/workflows/codecov.yml)
[![codecov](https://codecov.io/gh/duke-git/lancet/branch/main/graph/badge.svg?token=FC48T1F078)](https://codecov.io/gh/duke-git/lancet)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/duke-git/lancet/blob/main/LICENSE)
[![Gurubase](https://img.shields.io/badge/Gurubase-Ask%20Lancet%20Guru-006BFF)](https://gurubase.io/g/lancet)

</div>

<div STYLE="page-break-after: always;"></div>

<p style="font-size: 20px"> 
    Lancet is a comprehensive, efficient, and reusable util function library of go. Inspired by the java apache common package and lodash.js.
</p>

## <a href="https://www.golancet.cn/en/" target="_blank"> Website</a> | [简体中文](./README_zh-CN.md)

## Features

-   👏 Comprehensive, efficient and reusable.
-   💪 700+ go util functions, support string, slice, datetime, net, crypt...
-   💅 Only depends on two kinds of libraries: go standard library and golang.org/x.
-   🌍 Unit test for every exported function.

## Installation

### Note:

1. <b>For users who use go1.18 and above, it is recommended to install lancet v2.x.x. Cause in v2.x.x all functions were rewritten with generics of go1.18.</b>

```go
go get github.com/duke-git/lancet/v2 // will install latest version of v2.x.x
```

2. <b>For users who use version below go1.18, you should install v1.x.x. The latest of v1.x.x is v1.4.6. </b>

```go
go get github.com/duke-git/lancet // below go1.18, install latest version of v1.x.x
```

## Usage

Lancet organizes the code into package structure, and you need to import the corresponding package name when use it. For example, if you use string-related functions,import the strutil package like below:

```go
import "github.com/duke-git/lancet/v2/strutil"
```

## Example

Here takes the string function Reverse (reverse order string) as an example, and the strutil package needs to be imported.

```go
package main

import (
    "fmt"
    "github.com/duke-git/lancet/v2/strutil"
)

func main() {
    s := "hello"
    rs := strutil.Reverse(s)
    fmt.Println(rs) //olleh
}
```

## Documentation

### <span id="index">Index<span>

-   [Algorithm](#user-content-algorithm)
-   [Compare](#user-content-compare)
-   [Concurrency](#user-content-concurrency)
-   [Condition](#user-content-condition)
-   [Convertor](#user-content-convertor)
-   [Cryptor](#user-content-cryptor)
-   [Datetime](#user-content-datetime)
-   [Datastructure](#user-content-datastructure)
-   [EventBus](#user-content-eventbus)
-   [Enum](#user-content-enum)
-   [Fileutil](#user-content-fileutil)
-   [Formatter](#user-content-formatter)
-   [Function](#user-content-function)
-   [Maputil](#user-content-maputil)
-   [Mathutil](#user-content-mathutil)
-   [Netutil](#user-content-netutil)
-   [Pointer](#user-content-pointer)
-   [Random](#user-content-random)
-   [Retry](#user-content-retry)
-   [Slice](#user-content-slice)
-   [Stream](#user-content-stream)
-   [Structs](#user-content-structs)
-   [Strutil](#user-content-strutil)
-   [System](#user-content-system)
-   [Tuple](#user-content-tuple)
-   [Validator](#user-content-validator)
-   [Xerror](#user-content-xerror)

<h3 id="algorithm">1. Algorithm package implements some basic algorithm. eg. sort, search. &nbsp; &nbsp; &nbsp; &nbsp;<a href="#index">index</a></h3>

```go
import "github.com/duke-git/lancet/v2/algorithm"
```

#### Function list:

-   **<big>BubbleSort</big>** : sorts slice with bubble sort algorithm, will change the original slice.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/algorithm.md#BubbleSort)]
    [[play](https://go.dev/play/p/GNdv7Jg2Taj)]
-   **<big>CountSort</big>** : sorts slice with bubble sort algorithm, don't change original slice.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/algorithm.md#CountSort)]
    [[play](https://go.dev/play/p/tB-Umgm0DrP)]
-   **<big>HeapSort</big>** : sorts slice with heap sort algorithm, will change the original slice.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/algorithm.md#HeapSort)]
    [[play](https://go.dev/play/p/u6Iwa1VZS_f)]
-   **<big>InsertionSort</big>** : sorts slice with insertion sort algorithm, will change the original slice.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/algorithm.md#InsertionSort)]
    [[play](https://go.dev/play/p/G5LJiWgJJW6)]
-   **<big>MergeSort</big>** : sorts slice with merge sort algorithm, will change the original slice.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/algorithm.md#MergeSort)]
    [[play](https://go.dev/play/p/ydinn9YzUJn)]
-   **<big>QuickSort</big>** : sorts slice with quick sort algorithm, will change the original slice.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/algorithm.md#QuickSort)]
    [[play](https://go.dev/play/p/7Y7c1Elk3ax)]
-   **<big>SelectionSort</big>** : sorts slice with selection sort algorithm, will change the original slice.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/algorithm.md#SelectionSort)]
    [[play](https://go.dev/play/p/oXovbkekayS)]
-   **<big>ShellSort</big>** : sorts slice with shell sort algorithm, will change the original slice.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/algorithm.md#ShellSort)]
    [[play](https://go.dev/play/p/3ibkszpJEu3)]
-   **<big>BinarySearch</big>** : returns the index of target within a sorted slice, use binary search (recursive call itself).
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/algorithm.md#BinarySearch)]
    [[play](https://go.dev/play/p/t6MeGiUSN47)]
-   **<big>BinaryIterativeSearch</big>** : returns the index of target within a sorted slice, use binary search (no recursive).
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/algorithm.md#BinaryIterativeSearch)]
    [[play](https://go.dev/play/p/Anozfr8ZLH3)]
-   **<big>LinearSearch</big>** : returns the index of target in slice base on equal function.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/algorithm.md#LinearSearch)]
    [[play](https://go.dev/play/p/IsS7rgn5s3x)]
-   **<big>LRUCache</big>** : implements memory cache with lru algorithm.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/algorithm.md#LRUCache)]
    [[play](https://go.dev/play/p/-EZjgOURufP)]

<h3 id="compare"> 2. Compare package provides a lightweight comparison function on any type. &nbsp; &nbsp; &nbsp; &nbsp;<a href="#index">index</a> </h3>

```go
import "github.com/duke-git/lancet/v2/compare"
```

#### Function list:

-   **<big>Equal</big>** : Checks if two values are equal or not. (check both type and value)
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/compare.md#Equal)]
    [[play](https://go.dev/play/p/wmVxR-to4lz)]
-   **<big>EqualValue</big>** : Checks if two values are equal or not. (check value only)
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/compare.md#EqualValue)]
    [[play](https://go.dev/play/p/fxnna_LLD9u)]
-   **<big>LessThan</big>** : Checks if value `left` less than value `right`.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/compare.md#LessThan)]
    [[play](https://go.dev/play/p/cYh7FQQj0ne)]
-   **<big>GreaterThan</big>** : Checks if value `left` greater than value `right`.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/compare.md#GreaterThan)]
    [[play](https://go.dev/play/p/9-NYDFZmIMp)]
-   **<big>LessOrEqual</big>** : Checks if value `left` less than or equal than value `right`.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/compare.md#LessOrEqual)]
    [[play](https://go.dev/play/p/e4T_scwoQzp)]
-   **<big>GreaterOrEqual</big>** : Checks if value `left` less greater or equal than value `right`.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/compare.md#GreaterOrEqual)]
    [[play](https://go.dev/play/p/vx8mP0U8DFk)]
-   **<big>InDelta</big>** : Checks if two values are equal or not within a delta.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/compare.md#InDelta)]

<h3 id="concurrency"> 3. Concurrency package contain some functions to support concurrent programming. eg, goroutine, channel, async. &nbsp; &nbsp; &nbsp; &nbsp;<a href="#index">index</a> </h3>

```go
import "github.com/duke-git/lancet/v2/concurrency"
```

#### Function list:

-   **<big>NewChannel</big>** : create a Channel pointer instance.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/concurrency.md#NewChannel)]
    [[play](https://go.dev/play/p/7aB4KyMMp9A)]
-   **<big>Bridge</big>** : link multiply channels into one channel.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/Bridge.md#NewChannel)]
    [[play](https://go.dev/play/p/qmWSy1NVF-Y)]
-   **<big>FanIn</big>** : merge multiple channels into one channel.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/concurrency.md#FanIn)]
    [[play](https://go.dev/play/p/2VYFMexEvTm)]
-   **<big>Generate</big>** : creates a channel, then put values into the channel.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/concurrency.md#Generate)]
    [[play](https://go.dev/play/p/7aB4KyMMp9A)]
-   **<big>Or</big>** : read one or more channels into one channel, will close when any readin channel is closed.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/concurrency.md#Or)]
    [[play](https://go.dev/play/p/Wqz9rwioPww)]
-   **<big>OrDone</big>** : read a channel into another channel, will close until cancel context.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/concurrency.md#OrDone)]
    [[play](https://go.dev/play/p/lm_GoS6aDjo)]
-   **<big>Repeat</big>** : create channel, put values into the channel repeatedly until cancel the context.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/concurrency.md#Repeat)]
    [[play](https://go.dev/play/p/k5N_ALVmYjE)]
-   **<big>RepeatFn</big>** : create a channel, executes fn repeatedly, and put the result into the channel, until close context.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/concurrency.md#RepeatFn)]
    [[play](https://go.dev/play/p/4J1zAWttP85)]
-   **<big>Take</big>** : create a channel whose values are taken from another channel with limit number.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/concurrency.md#Take)]
    [[play](https://go.dev/play/p/9Utt-1pDr2J)]
-   **<big>Tee</big>** : split one chanel into two channels, until cancel the context.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/concurrency.md#Tee)]
    [[play](https://go.dev/play/p/3TQPKnCirrP)]
-   **<big>NewKeyedLocker</big>** : KeyedLocker is a simple implementation of a keyed locker that allows for non-blocking lock acquisition.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/concurrency.md#NewKeyedLocker)]
    [[play](https://go.dev/play/p/GzeyC33T5rw)]
-   **<big>Do</big>** :acquires a lock for the specified key and executes the provided function.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/concurrency.md#Do)]
    [[play](https://go.dev/play/p/GzeyC33T5rw)]
-   **<big>NewRWKeyedLocker</big>** :RRWKeyedLocker is a read-write version of KeyedLocker.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/concurrency.md#NewRWKeyedLocker)]
    [[play](https://go.dev/play/p/ZrCr8sMo77T)]
-   **<big>RLock</big>** : acquires a read lock for the specified key and executes the provided function.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/concurrency.md#RLock)]
    [[play](https://go.dev/play/p/ZrCr8sMo77T)]
-   **<big>Lock</big>** : acquires a write lock for the specified key and executes the provided function.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/concurrency.md#Lock)]
    [[play](https://go.dev/play/p/WgAcXbOPKGk)]
-   **<big>NewTryKeyedLocker</big>** : TryKeyedLocker is a non-blocking version of KeyedLocker.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/concurrency.md#NewTryKeyedLocker)]
    [[play](https://go.dev/play/p/VG9qLvyetE2)]
-   **<big>TryLock</big>** : TryLock tries to acquire a lock for the specified key.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/concurrency.md#TryLock)]
    [[play](https://go.dev/play/p/VG9qLvyetE2)]
-   **<big>Unlock</big>** : Unlock releases the lock for the specified key.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/concurrency.md#Unlock)]
    [[play](https://go.dev/play/p/VG9qLvyetE2)]

<h3 id="condition"> 4. Condition package contains some functions for conditional judgment. eg. And, Or, TernaryOperator...&nbsp; &nbsp; &nbsp; &nbsp;<a href="#index">index</a> </h3>

```go
import "github.com/duke-git/lancet/v2/condition"
```

#### Function list:

-   **<big>Bool</big>** : returns the truthy value of anything.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/condition.md#Bool)]
    [[play](https://go.dev/play/p/ETzeDJRSvhm)]
-   **<big>And</big>** : returns true if both a and b are truthy.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/condition.md#And)]
    [[play](https://go.dev/play/p/W1SSUmt6pvr)]
-   **<big>Or</big>** : returns false if neither a nor b is truthy.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/condition.md#Or)]
    [[play](https://go.dev/play/p/UlQTxHaeEkq)]
-   **<big>Xor</big>** : returns true if a or b but not both is truthy.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/condition.md#Xor)]
    [[play](https://go.dev/play/p/gObZrW7ZbG8)]
-   **<big>Nor</big>** : returns true if neither a nor b is truthy.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/condition.md#Nor)]
    [[play](https://go.dev/play/p/g2j08F_zZky)]
-   **<big>Xnor</big>** : returns true if both a and b or neither a nor b are truthy.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/condition.md#Xnor)]
    [[play](https://go.dev/play/p/OuDB9g51643)]
-   **<big>Nand</big>** : returns false if both a and b are truthy.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/condition.md#Nand)]
    [[play](https://go.dev/play/p/vSRMLxLIbq8)]
-   **<big>TernaryOperator</big>** : ternary operator.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/condition.md#TernaryOperator)]
    [[play](https://go.dev/play/p/ElllPZY0guT)]

<h3 id="convertor"> 5. Convertor package contains some functions for data conversion. &nbsp; &nbsp; &nbsp; &nbsp;<a href="#index">index</a> </h3>

```go
import "github.com/duke-git/lancet/v2/convertor"
```

#### Function list:

-   **<big>ColorHexToRGB</big>** : convert color hex to color rgb.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/convertor.md#ColorHexToRGB)]
    [[play](https://go.dev/play/p/o7_ft-JCJBV)]
-   **<big>ColorRGBToHex</big>** : convert rgb color to hex color.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/convertor.md#ColorRGBToHex)]
    [[play](https://go.dev/play/p/nzKS2Ro87J1)]
-   **<big>ToBool</big>** : convert string to bool.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/convertor.md#ToBool)]
    [[play](https://go.dev/play/p/ARht2WnGdIN)]
-   **<big>ToBytes</big>** : convert value to byte slice.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/convertor.md#ToBytes)]
    [[play](https://go.dev/play/p/fAMXYFDvOvr)]
-   **<big>ToChar</big>** : convert string to char slice.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/convertor.md#ToChar)]
    [[play](https://go.dev/play/p/JJ1SvbFkVdM)]
-   **<big>ToChannel</big>** : convert a collection of elements to a read-only channel.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/convertor.md#ToChannel)]
    [[play](https://go.dev/play/p/hOx_oYZbAnL)]
-   **<big>ToFloat</big>** : convert value to float64, if param is a invalid floatable, will return 0.0 and error.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/convertor.md#ToFloat)]
    [[play](https://go.dev/play/p/4YTmPCibqHJ)]
-   **<big>ToInt</big>** : convert value to int64 value, if input is not numerical, return 0 and error.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/convertor.md#ToInt)]
    [[play](https://go.dev/play/p/9_h9vIt-QZ_b)]
-   **<big>ToJson</big>** : convert value to a json string.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/convertor.md#ToJson)]
    [[play](https://go.dev/play/p/2rLIkMmXWvR)]
-   **<big>ToMap</big>** : convert a slice of structs to a map based on iteratee function.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/convertor.md#ToMap)]
    [[play](https://go.dev/play/p/tVFy7E-t24l)]
-   **<big>ToPointer</big>** : return a pointer of passed value.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/convertor.md#ToPointer)]
    [[play](https://go.dev/play/p/ASf_etHNlw1)]
-   **<big>ToPointers</big>** : convert a slice of values to a slice of pointers.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/convertor.md#ToPointers)]
    [[play](https://go.dev/play/p/ZUoXd2i5ZkV)]
-   **<big>FromPointer</big>** : returns the value pointed to by the pointer.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/convertor.md#FromPointer)]
    [[play](https://go.dev/play/p/wAp90V7Zu6g)]
-   **<big>FromPointers</big>** : convert a slice of pointers to a slice of values.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/convertor.md#FromPointers)]
    [[play](https://go.dev/play/p/qIPsyYtNy3Q)]
-   **<big>ToString</big>** : convert value to string.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/convertor.md#ToString)]
    [[play](https://go.dev/play/p/nF1zOOslpQq)]
-   **<big>StructToMap</big>** : convert struct to map, only convert exported struct field.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/convertor.md#StructToMap)]
    [[play](https://go.dev/play/p/KYGYJqNUBOI)]
-   **<big>MapToSlice</big>** : convert map to slice based on iteratee function.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/convertor.md#MapToSlice)]
    [[play](https://go.dev/play/p/dmX4Ix5V6Wl)]
-   **<big>EncodeByte</big>** : encode data to byte slice.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/convertor.md#EncodeByte)]
    [[play](https://go.dev/play/p/DVmM1G5JfuP)]
Frequently Asked Questions

What is lancet?
lancet is a Text Processing library for the Go programming language. A comprehensive, Lodash-like utility library for Go
How many GitHub stars does lancet have?
lancet has 5,296 GitHub stars in the directory's latest synchronization.
How do I install lancet?
Install lancet with the Go module system using `go get duke-git/lancet`. Check the repository for the current installation instructions.
What category does lancet belong to?
lancet is listed under Text Processing, specifically Utility/Miscellaneous.
← Back to Utility/Miscellaneous