Skip to content

Commit

Permalink
Update doc
Browse files Browse the repository at this point in the history
  • Loading branch information
@orbisgloria
orbisgloria committed Dec 1, 2024
1 parent 9d6cb7f commit fdcc500
Show file tree
Hide file tree
Showing 7 changed files with 706 additions and 64 deletions.
191 changes: 149 additions & 42 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,64 +3,171 @@

# is

Is package provides various validation functions to check the correctness of different types of data. It offers a collection of functions to validate data such as numbers, strings, geographic coordinates, email addresses, e-mail, bank card number, bank account IBAN, phone and more.
The `is` package provides a comprehensive set of validation functions for various data types commonly used in web applications, financial systems, and general software development. It offers a clean, efficient way to validate data formats ranging from basic types to complex financial and network identifiers.

## Features

### Account & Identity Validation
- `Email(string) bool` - Email addresses
- `Nickname(string, ...bool) bool` - Usernames (with optional strict mode)
- `VariableName(string, ...bool) bool` - Programming variable names
- `VariableNameFor(string, string) (bool, error)` - Language-specific variable names

### Financial Validation
- `BankCard(string, ...*regexp.Regexp) bool` - Credit/Debit card numbers with optional card type checking
- `IBAN(string, ...bool) bool` - International Bank Account Numbers
- `Iban(string, ...bool) bool` - Alias for IBAN validation

### Geographic Validation
- `Latitude[T string|float64](T) bool` - Latitude coordinates
- `Longitude[T string|float64](T) bool` - Longitude coordinates
- `Coordinates[T string|float64](lat, lon T) bool` - Coordinate pairs

### Network & Communication
- `IPv4(string) bool` - IPv4 addresses
- `IPv6(string) bool` - IPv6 addresses
- `IP(string) bool` - Any IP address (v4 or v6)
- `Phone(string) bool` - Phone numbers
- `E164(string) bool` - E.164 format phone numbers

### String Type Validation
- `Alpha(string) bool` - Alphabetic characters
- `Alnum(string) bool` - Alphanumeric characters
- `Digit(string) bool` - Numeric digits only
- `Lower(string) bool` - Lowercase letters
- `Upper(string) bool` - Uppercase letters
- `Title(string) bool` - Title case text
- `Space(string) bool` - Whitespace characters
- `Numeric(string) bool` - Numeric strings (including decimals)
- `Decimal(string) bool` - Decimal numbers
- `Float(string) bool` - Floating-point numbers

### Number Type Validation
- `Even[T Numerable](T, ...bool) bool` - Even numbers
- `Odd[T Numerable](T, ...bool) bool` - Odd numbers
- `Whole[T Numerable](T) bool` - Whole numbers
- `Natural[T Numerable](T) bool` - Natural numbers
- `Positive[T Numerable](T) bool` - Positive numbers
- `Negative[T Numerable](T) bool` - Negative numbers
- `Zero[T Numerable](T) bool` - Zero value check

### Encoding & Format Validation
- `Base64(string) bool` - Base64 encoding
- `Base64URL(string) bool` - URL-safe Base64 encoding
- `Hex(string) bool` - Hexadecimal strings
- `Bin(string) bool` - Binary strings
- `HexColor(string) bool` - Hexadecimal color codes
- `RGBColor(string) bool` - RGB color format
- `MD5(string) bool` - MD5 hash strings
- `JWT(string) bool` - JSON Web Tokens

### Mobile & Telecom
- `IMEI[T string|int64](T) bool` - International Mobile Equipment Identity
- `IMSI(string) bool` - International Mobile Subscriber Identity

## Note

The package provides validation functions that do not pre-clean the data. If the validation data needs to be cleaned, it must be cleaned beforehand, for example, using the [g package](https://github.com/goloop/g), as `g.Weed`, `g.Trim` etc.
## Installation

```shell
go get -u github.com/goloop/is
```

## Installation
## Important Note

To use the Go Is package in your project, you need to install it using the go get command:
The package provides validation functions that do not pre-clean the data. If the validation data needs to be cleaned, it must be cleaned beforehand, for example, using the [g package](https://github.com/goloop/g).

```shell
go get github.com/goloop/is
Example:
```go
raw := "GB82 WEST 1234 5698 7654 32" // contains spaces
iban := g.Weed(raw, g.Whitespaces) // remove spaces
valid := is.IBAN(iban) // validate
```

## Usage
## Usage Examples

### Basic Validation

```go
package main

import (
"fmt"
"github.com/goloop/is"
)

func main() {
// Email validation.
fmt.Println(is.Email("[email protected]")) // true
fmt.Println(is.Email("invalid-email")) // false

// Phone number validation.
fmt.Println(is.Phone("+1 (234) 567-8900")) // true
fmt.Println(is.E164("+12345678900")) // true

// Geographic coordinates.
fmt.Println(is.Coordinates(51.5074, -0.1278)) // true
fmt.Println(is.Coordinates(91.0, 0.0)) // false

// Financial validation.
fmt.Println(is.BankCard("4111111111111111")) // true
fmt.Println(is.IBAN("DE89370400440532013000")) // true
}
```

Here's an example of how to use the Go Is package to validate different types of data:
### Advanced Validation

```go
package main

import (
"fmt"
"github.com/goloop/is"
"fmt"
"github.com/goloop/is"
)

func main() {
// Validate a phone number.
phoneNum := "+380 (96) 46 200 00"
if is.Phone(phoneNum) {
fmt.Println("Valid phone number")
} else {
fmt.Println("Invalid phone number")
}

// Validate an email address
email := "[email protected]"
if is.Email(email) {
fmt.Println("Valid email address")
} else {
fmt.Println("Invalid email address")
}

// Validate geographic coordinates
latitude := 37.7749
longitude := -122.4194
if is.Coordinates(latitude, longitude) {
fmt.Println("Valid coordinates")
} else {
fmt.Println("Invalid coordinates")
}

// Output:
// Valid phone number
// Valid email address
// Valid coordinates
// Variable name validation for different languages.
fmt.Println(is.VariableNameFor("myVar", "go")) // true
fmt.Println(is.VariableNameFor("class", "python")) // false (reserved word)

// Strict mode validation.
fmt.Println(is.Nickname("user123", true)) // true
fmt.Println(is.Nickname("user@123", true)) // false

// Number validation.
fmt.Println(is.Even(4)) // true
fmt.Println(is.Natural(5)) // true
fmt.Println(is.Positive(-1)) // false

// Format validation.
fmt.Println(is.HexColor("#FF5733")) // true
fmt.Println(is.Base64("SGVsbG8=")) // true
fmt.Println(is.JWT("eyJhbGciOiJIUzI...")) // true
}
```

This example demonstrates how to use the Go Is package to validate a phone number, email address, and geographic coordinates. You can import the github.com/goloop/is package and call the corresponding validation functions for the specific data you want to validate. The functions will return a boolean value indicating whether the data is valid or not.
## Contributing

Contributions are welcome! Here are a few ways you can help:

1. Report bugs by opening an issue
2. Suggest new features or improvements
3. Submit pull requests
4. Improve documentation
5. Share the package with others

Please make sure to:
- Write tests for new features
- Follow Go coding standards
- Update documentation as needed
- Add comments to explain complex logic

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Credits

Created and maintained by [Goloop Team](https://github.com/goloop)

## Related Projects

- [g](https://github.com/goloop/g) - Go utility functions package
58 changes: 58 additions & 0 deletions benchmarks.txt
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
goos: linux
goarch: arm64
pkg: github.com/goloop/is
BenchmarkNickname/ValidSimple-6 4546402 263.4 ns/op 0 B/op 0 allocs/op
BenchmarkNickname/ValidUnicode-6 5315379 225.8 ns/op 0 B/op 0 allocs/op
BenchmarkNickname/ValidStrict-6 8445592 144.4 ns/op 0 B/op 0 allocs/op
BenchmarkNickname/Invalid-6 6793458 177.7 ns/op 0 B/op 0 allocs/op
BenchmarkNickname/InvalidStrict-6 18293379 66.35 ns/op 0 B/op 0 allocs/op
BenchmarkBankCard/ValidVisa-6 4288795 281.7 ns/op 0 B/op 0 allocs/op
BenchmarkBankCard/ValidMasterCard-6 4697384 255.5 ns/op 0 B/op 0 allocs/op
BenchmarkBankCard/ValidAmEx-6 4346312 279.8 ns/op 0 B/op 0 allocs/op
BenchmarkBankCard/Invalid-6 18940783 63.39 ns/op 0 B/op 0 allocs/op
BenchmarkIBAN/ValidGB-6 579920 2035 ns/op 808 B/op 55 allocs/op
BenchmarkIBAN/ValidDE-6 691213 1675 ns/op 704 B/op 54 allocs/op
BenchmarkIBAN/Invalid-6 4199583 288.5 ns/op 160 B/op 7 allocs/op
BenchmarkVariableName/ValidSimple-6 5799820 216.7 ns/op 128 B/op 5 allocs/op
BenchmarkVariableName/ValidStrict-6 1000000 1087 ns/op 128 B/op 5 allocs/op
BenchmarkVariableName/Invalid-6 41859518 27.37 ns/op 1 B/op 1 allocs/op
BenchmarkEmail/Valid-6 1529440 781.7 ns/op 32 B/op 1 allocs/op
BenchmarkEmail/ValidComplex-6 1582082 761.6 ns/op 32 B/op 1 allocs/op
BenchmarkEmail/Invalid-6 33812802 35.14 ns/op 16 B/op 1 allocs/op
BenchmarkEmail/InvalidFormat-6 587890792 2.019 ns/op 0 B/op 0 allocs/op
BenchmarkLatitude/ValidPositive-6 11015227 107.7 ns/op 16 B/op 2 allocs/op
BenchmarkLatitude/ValidNegative-6 10721606 115.6 ns/op 16 B/op 2 allocs/op
BenchmarkLatitude/Invalid-6 10836784 112.4 ns/op 16 B/op 2 allocs/op
BenchmarkLongitude/ValidPositive-6 10270970 114.0 ns/op 16 B/op 2 allocs/op
BenchmarkLongitude/ValidNegative-6 10189796 116.0 ns/op 16 B/op 2 allocs/op
BenchmarkLongitude/Invalid-6 10541376 112.1 ns/op 16 B/op 2 allocs/op
BenchmarkMD5/Valid-6 2706142 447.0 ns/op 0 B/op 0 allocs/op
BenchmarkMD5/Invalid-6 605684750 1.992 ns/op 0 B/op 0 allocs/op
BenchmarkIPv4/Valid-6 13901445 85.26 ns/op 64 B/op 1 allocs/op
BenchmarkIPv4/ValidLocalhost-6 14410293 88.03 ns/op 64 B/op 1 allocs/op
BenchmarkIPv4/Invalid-6 16114604 71.90 ns/op 64 B/op 1 allocs/op
BenchmarkIPv6/Valid-6 14128792 84.76 ns/op 0 B/op 0 allocs/op
BenchmarkIPv6/ValidShort-6 38995820 30.48 ns/op 0 B/op 0 allocs/op
BenchmarkIPv6/Invalid-6 22866658 44.15 ns/op 48 B/op 1 allocs/op
BenchmarkEven/ValidEven-6 9735872 128.2 ns/op 128 B/op 4 allocs/op
BenchmarkEven/InvalidOdd-6 9487488 129.3 ns/op 128 B/op 4 allocs/op
BenchmarkOdd/ValidOdd-6 10003414 119.7 ns/op 128 B/op 4 allocs/op
BenchmarkOdd/InvalidEven-6 9941060 122.0 ns/op 128 B/op 4 allocs/op
BenchmarkE164/Valid-6 7082565 167.0 ns/op 0 B/op 0 allocs/op
BenchmarkE164/Invalid-6 41346447 28.79 ns/op 0 B/op 0 allocs/op
BenchmarkE164/InvalidFormat-6 14475134 81.19 ns/op 0 B/op 0 allocs/op
BenchmarkPhone/Valid-6 2910463 410.5 ns/op 24 B/op 2 allocs/op
BenchmarkPhone/ValidWithSpaces-6 2837608 430.8 ns/op 24 B/op 2 allocs/op
BenchmarkPhone/Invalid-6 5392218 223.1 ns/op 24 B/op 2 allocs/op
BenchmarkDigit/Valid-6 139367886 8.809 ns/op 0 B/op 0 allocs/op
BenchmarkDigit/Invalid-6 124452582 9.519 ns/op 0 B/op 0 allocs/op
BenchmarkNumeric/ValidInteger-6 9895348 122.4 ns/op 0 B/op 0 allocs/op
BenchmarkNumeric/ValidDecimal-6 9229262 127.4 ns/op 0 B/op 0 allocs/op
BenchmarkNumeric/ValidNegative-6 9266892 130.4 ns/op 0 B/op 0 allocs/op
BenchmarkNumeric/Invalid-6 8133463 146.0 ns/op 0 B/op 0 allocs/op
BenchmarkAlpha/Valid-6 121680956 9.931 ns/op 0 B/op 0 allocs/op
BenchmarkAlpha/Invalid-6 163999609 7.345 ns/op 0 B/op 0 allocs/op
BenchmarkAlnum/Valid-6 89381952 13.90 ns/op 0 B/op 0 allocs/op
BenchmarkAlnum/Invalid-6 80839196 14.77 ns/op 0 B/op 0 allocs/op
PASS
ok github.com/goloop/is 75.415s
Loading

0 comments on commit fdcc500

Please sign in to comment.