Merge pull request #3 from go-andiamo/implementation

Full implementation
go-andiamo · Nov 11, 2022 · 532d6e1 · 532d6e1
2 parents 6680670 + 312d6ae
commit 532d6e1
Show file tree

Hide file tree

Showing 5 changed files with 543 additions and 21 deletions.
diff --git a/README.md b/README.md
@@ -4,4 +4,200 @@
 [![codecov](https://codecov.io/gh/go-andiamo/gopt/branch/main/graph/badge.svg?token=igjnZdgh0e)](https://codecov.io/gh/go-andiamo/gopt)
 [![Go Report Card](https://goreportcard.com/badge/github.com/go-andiamo/gopt)](https://goreportcard.com/report/github.com/go-andiamo/gopt)
 
-A very simple Optional implementation in Golang
+A very light Optional implementation in Golang
+
+## Installation
+To install Gopt, use go get:
+
+    go get github.com/go-andiamo/gopt
+
+To update Gopt to the latest version, run:
+
+    go get -u github.com/go-andiamo/gopt
+
+## Examples
+```go
+package main
+
+import (
+    . "github.com/go-andiamo/gopt"
+)
+
+func main() {
+    optFlt := Of[float64](1.23)
+    println(optFlt.IsPresent())
+    println(optFlt.OrElse(-1))
+
+    opt2 := Empty[float64]()
+    println(opt2.IsPresent())
+    println(opt2.OrElse(-1))
+
+    opt2.OrElseSet(10)
+    println(opt2.IsPresent())
+    println(opt2.OrElse(-1))
+}
+```
+
+## Methods
+<table>
+    <tr>
+        <th>Method and description</th>
+        <th>Returns</th>
+    </tr>
+    <tr>
+        <td>
+            <code>Get()</code><br>
+            returns the value and an error if the value is not present
+        </td>
+        <td><code>(T, error)</code></td>
+    </tr>
+    <tr>
+        <td>
+            <code>AsEmpty()</code><br>
+            returns a new empty optional of the same type
+        </td>
+        <td><code>Optional[T]</code></td>
+    </tr>
+    <tr>
+        <td>
+            <code>IsPresent()</code><br>
+            returns true if the value is present, otherwise false
+        </td>
+        <td><code>bool</code></td>
+    </tr>
+    <tr>
+        <td>
+            <code>IfPresent(f func(v T))</code><br>
+            if the value is present, calls the supplied function with the value, otherwise does nothing<br>
+            <em>returns the original optional</em>
+        </td>
+        <td><code>Optional[T]</code></td>
+    </tr>
+    <tr>
+        <td>
+            <code>IfPresentOtherwise(f func(v T), other func())</code><br>
+            if the value is present, calls the supplied function with the value, otherwise calls the other function<br>
+            <em>returns the original optional</em>
+        </td>
+        <td><code><code>Optional[T]</code></code></td>
+    </tr>
+    <tr>
+        <td>
+            <code>OrElse(other T)</code><br>
+            returns the value if present, otherwise returns other
+        </td>
+        <td><code>T</code></td>
+    </tr>
+    <tr>
+        <td>
+            <code>OrElseGet(f func() T)</code><br>
+            returns the value if present, otherwise returns the result of calling the supplied function
+        </td>
+        <td><code>T</code></td>
+    </tr>
+    <tr>
+        <td>
+            <code>OrElseSet(v T)</code><br>
+            if the value is not present it is set to the supplied value
+        </td>
+        <td><code>Optional[T]</code></td>
+    </tr>
+    <tr>
+        <td>
+            <code>OrElseError(err error)</code><br>
+            returns the supplied error if the value is not present, otherwise returns nil
+        </td>
+        <td><code>error</code></td>
+    </tr>
+    <tr>
+        <td>
+            <code>OrElsePanic(v any)</code><br>
+            if the value is not present, panics with the supplied value, otherwise does nothing
+        </td>
+        <td><em>nothing</em></td>
+    </tr>
+    <tr>
+        <td>
+            <code>DoWith(f func(v T))</code><br>
+            if the value is present, calls the supplied function with the value<br>
+            <em>returns the original optional</em>
+        </td>
+        <td><code>Optional[T]</code></td>
+    </tr>
+    <tr>
+        <td>
+            <code>Filter(f func(v T) bool)</code><br>
+            if the value is present and calling the supplied filter function returns true, returns a new optional describing the value<br>
+            Otherwise returns an empty optional
+        </td>
+        <td><code>Optional[T]</code></td>
+    </tr>
+    <tr>
+        <td>
+            <code>Map(f func(v T) any)</code><br>
+            if the value is present and the result of calling the supplied mapping function returns non-nil, returns
+            an optional describing that returned value<br>
+            Otherwise returns an empty optional
+        </td>
+        <td><code>Optional[any]</code></td>
+    </tr>
+    <tr>
+        <td>
+            <code>MarshalJSON()</code><br>
+            implements JSON marshal<br>
+            if the value is present, returns the marshalled data for the value<br>
+            Otherwise, returns the marshalled data for null
+        </td>
+        <td><code>([]byte, error)</code></td>
+    </tr>
+    <tr>
+        <td>
+            <code>UnmarshalJSON(data []byte)</code><br>
+            implements JSON unmarshal<br>
+            if the supplied data is null representation, sets the present to false<br>
+            Otherwise, unmarshal the data as the value and sets the optional to present (unless the result of
+            unmarshalling the value returns an error - in which case the present is set to false)
+        </td>
+        <td><code>error</code></td>
+    </tr>
+    <tr>
+        <td>
+            <code>Scan(value interface{})</code><br>
+            implements sql.Scan
+        </td>
+        <td><code>error</code></td>
+    </tr>
+</table>
+
+## Constructors
+<table>
+    <tr>
+        <th>Constructor function and description</th>
+    </tr>
+    <tr>
+        <td>
+            <code>Of[T any](value T) Optional[T]</code><br>
+            Creates a new optional with the supplied value
+        </td>
+    </tr>
+    <tr>
+        <td>
+            <code>OfNillable[T any](value T) Optional[T]</code><br>
+            Creates a new optional with the supplied value<br>
+            If the supplied value is nil, an empty (not present) optional is returned
+        </td>
+    </tr>
+    <tr>
+        <td>
+            <code>OfNillableString(value string) Optional[string]</code><br>
+            Creates a new string optional with the supplied value<br>
+            If the supplied value is an empty string, an empty (not-present) optional is returned
+        </td>
+    </tr>
+    <tr>
+        <td>
+            <code>Empty[T any]() Optional[T]</code><br>
+            Creates a new empty (not-present) optional of the specified type
+        </td>
+    </tr>
+</table>
diff --git a/go.mod b/go.mod
@@ -6,6 +6,8 @@ require github.com/stretchr/testify v1.8.1
 
 require (
 	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/kr/text v0.2.0 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
+	gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )
diff --git a/go.sum b/go.sum
@@ -1,6 +1,13 @@
+github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/kr/pretty v0.2.1 h1:Fmg33tUaq4/8ym9TJN1x7sLJnHVwhP33CNkpYV/7rwI=
+github.com/kr/pretty v0.2.1/go.mod h1:ipq/a2n7PKx3OHsz4KJII5eveXtPO4qwEXGdVfWzfnI=
+github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
+github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
@@ -10,8 +17,9 @@ github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/
 github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
 github.com/stretchr/testify v1.8.1 h1:w7B6lhMri9wdJUVmEZPGGhZzrYTPvgJArz7wNPgYKsk=
 github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
-gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=