# Operators - Common Combinators

These generic functions and operators are used commonly and are not part of any other abstraction.

You can find these in the API docs: Operators.fs

## flip

Creates a new function with first two arguments flipped.

## konst

Create a function that always returns the given argument. This is known as a 'constant' function.

This is commonly useful where a function is required as a parameter for flexibility, but isn't required in a specific instance.

example:

let a = [1;2;3] |> filter (konst true);;
// val a : int list = [1; 2; 3]


## curry, uncurry, curryN, uncurryN

Currying is the process of taking a function expecting a tuple, and returning a function with the same number of arguments as the tuple size.

Uncurrying is the reverse process.

There is curry and uncurry that work on two arguments each, while curryN and uncurryN work on any number.

example:

let addThreeNums (x, y, z) = x + y + z;;
// val addThreeNums : x:int * y:int * z:int -> int

let b = curryN addThreeNums 1 2 3;;
// val it : int = 6


## Functions as operators -

A pair of operators </ and /> are defined to allow any function to be used as an operator. It will flip the args of your function so that it makes sense when the first argument is coming from the left-hand-side.

example:

let biggerThan a b = a > b;;
// val biggerThan : a:'a -> b:'a -> bool when 'a : comparison

let c = 10 </biggerThan/> 3;;
// val c : bool = true


## tap

Tap executes a side-effect function, then returns the original input value. Consider this as 'tapping into' a chain of functions.

example:

// a pipeline of functions, with a tap in the middle
let names = ["John"; "Smith"]
names |> map String.toUpper |> tap (printfn "%A") |> map String.toLower;;

// prints this:
// ["JOHN"; "SMITH"]

// but returns this:
// val it : string list = ["john"; "smith"]


## either

Extracts the value inside a Result from either side - whether Ok or Error.

It takes a pair of functions:

• fOk - a function applied to the source if it contains an Ok value
• fError - a function applied to the source if it contains an Error value

...and the source:

• source - the source value containing an Ok or Error
let myResult = Ok "I am ok!";;
// val myResult : Result<string,'a>

let myOther = Error -1;;
// val myOther : Result<'a,int>

let d = either id id myResult;;
// val d : string = "I am ok!"

let e = either id id myOther;;
// val e : int = -1


Don't confuse the either function with result which lifts a value into a Functor, just like return when in a computation expression.

## option

Takes a function, a default value and a option value. If the option value is None, the function returns the default value. Otherwise, it applies the function to the value inside Some and returns the result.

let inline option f n = function Some x -> f x | None -> n


## tuple2, tuple3, ...tuple8

Functions that generate a tuple. The number indicates the number of arguments that are defined, and the corresponding size of tuple.

let inline tuple2 a b             = a,b
let inline tuple3 a b c           = a,b,c
let inline tuple4 a b c d         = a,b,c,d
let inline tuple5 a b c d e       = a,b,c,d,e
let inline tuple6 a b c d e f     = a,b,c,d,e,f
let inline tuple7 a b c d e f g   = a,b,c,d,e,f,g
let inline tuple8 a b c d e f g h = a,b,c,d,e,f,g,h


## Explicit

Explicit allows you to use explicit generic method for standard types and types that implement the static explicit type cast signature.

### Minimal definition

In order to use the explicit generic method together with a type it needs to implement the following:

 static member op_Explicit (x:'r) :'T 

or in C#

 public static explicit operator T(R s) 

This is useful when dealing with C# libraries that make heavy use of explicit conversions.

## Implicit

Implicit allows you to use implicit generic method for standard types and types that implement the static implicit type cast signature.

### Minimal definition

In order to use the implicit generic method together with a type it needs to implement the following:

 static member op_Implicit (x:'r) :'T 

or in C#

 public static implicit operator T(R s) 

This is useful when dealing with C# libraries that make heavy use of implicit conversions.

namespace FSharpPlus
val a: int list
val filter: predicate: ('T -> bool) -> source: 'Collection<'T> -> 'Collection<'T> (requires member Filter)
<summary>Returns a new collection containing only the elements of the collection for which the given predicate returns "true"</summary>
<category index="19">Collection</category>
<param name="predicate">The function to test the input elements.</param>
<param name="source">The input collection.</param>
<returns>A collection containing only the elements that satisfy the predicate.</returns>
val konst: k: 'T -> 'Ignored -> 'T
<summary> Creates a constant function.</summary>
<param name="k">The constant value.</param>
<returns>The constant value function.</returns>
<category index="0">Common Combinators</category>
val addThreeNums: x: int * y: int * z: int -> int
val x: int
val y: int
val z: int
val b: int
val curryN: f: ('T1 * ^T2 * ... * ^Tn -> 'Result) -> t: 'T1 -> 'T2 -> ... -> 'Tn -> 'Result (requires member Curry)
<summary> Takes a function expecting a tuple of any N number of elements and returns a function expecting N curried arguments. </summary>
<category index="0">Common Combinators</category>
val biggerThan: a: 'a -> b: 'a -> bool (requires comparison)
val a: 'a (requires comparison)
val b: 'a (requires comparison)
val c: bool
val names: string list
val map: f: ('T -> 'U) -> x: 'Functor<'T> -> 'Functor<'U> (requires member Map)
<summary>Lifts a function into a Functor.</summary>
<category index="1">Functor</category>
Multiple items
module String from FSharpPlus
<summary> Additional operations on String </summary>

--------------------
module String from Microsoft.FSharp.Core
<summary>Functional programming operators for string processing. Further string operations are available via the member functions on strings and other functionality in <a href="http://msdn2.microsoft.com/en-us/library/system.string.aspx">System.String</a> and <a href="http://msdn2.microsoft.com/library/system.text.regularexpressions.aspx">System.Text.RegularExpressions</a> types. </summary>
<category>Strings and Text</category>
val toUpper: source: string -> string
<summary> Converts to uppercase -- nullsafe function wrapper for String.ToUpperInvariant method. </summary>
val tap: f: ('T -> unit) -> x: 'T -> 'T
<summary> Executes a side-effect function and returns the original input value. </summary>
<category index="0">Common Combinators</category>
val printfn: format: Printf.TextWriterFormat<'T> -> 'T
<summary>Print to <c>stdout</c> using the given format, and add a newline.</summary>
<param name="format">The formatter.</param>
<returns>The formatted result.</returns>
<example>See <c>Printf.printfn</c> (link: <see cref="M:Microsoft.FSharp.Core.PrintfModule.PrintFormatLine1" />) for examples.</example>
val toLower: source: string -> string
<summary> Converts to lowercase -- nullsafe function wrapper for String.ToLowerInvariant method. </summary>
val myResult: Result<string,'a>
union case Result.Ok: ResultValue: 'T -> Result<'T,'TError>
<summary> Represents an OK or a Successful result. The code succeeded with a value of 'T. </summary>
val myOther: Result<'a,int>
union case Result.Error: ErrorValue: 'TError -> Result<'T,'TError>
<summary> Represents an Error or a Failure. The code failed with a value of 'TError representing what went wrong. </summary>
val d: string
val either: fOk: ('T -> 'U) -> fError: ('Error -> 'U) -> source: Result<'T,'Error> -> 'U
<summary>Extracts a value from either side of a Result.</summary>
<category index="0">Common Combinators</category>
<param name="fOk">Function to be applied to source, if it contains an Ok value.</param>
<param name="fError">Function to be applied to source, if it contains an Error value.</param>
<param name="source">The source value, containing an Ok or an Error.</param>
<returns>The result of applying either functions.</returns>
val id: x: 'T -> 'T
<summary>The identity function</summary>
<param name="x">The input value.</param>
<returns>The same value.</returns>
<example id="id-example"><code lang="fsharp"> id 12 // Evaulates to 12 id "abc" // Evaulates to "abc" </code></example>
val e: int
Multiple items
val option: f: ('a -> 'b) -> n: 'b -> _arg1: 'a option -> 'b

--------------------
type 'T option = Option<'T>
<summary>The type of optional values. When used from other CLI languages the empty option is the <c>null</c> value. </summary>
<remarks>Use the constructors <c>Some</c> and <c>None</c> to create values of this type. Use the values in the <c>Option</c> module to manipulate values of this type, or pattern match against the values directly. 'None' values will appear as the value <c>null</c> to other CLI languages. Instance methods on this type will appear as static methods to other CLI languages due to the use of <c>null</c> as a value representation.</remarks>
<category index="3">Options</category>
val f: ('a -> 'b)
val n: 'b
union case Option.Some: Value: 'T -> Option<'T>
<summary>The representation of "Value of type 'T"</summary>
<param name="Value">The input value.</param>
<returns>An option representing the value.</returns>
val x: 'a
union case Option.None: Option<'T>
<summary>The representation of "No value"</summary>
val tuple2: a: 'a -> b: 'b -> 'a * 'b
val a: 'a
val b: 'b
val tuple3: a: 'a -> b: 'b -> c: 'c -> 'a * 'b * 'c
val c: 'c
val tuple4: a: 'a -> b: 'b -> c: 'c -> d: 'd -> 'a * 'b * 'c * 'd
val d: 'd
val tuple5: a: 'a -> b: 'b -> c: 'c -> d: 'd -> e: 'e -> 'a * 'b * 'c * 'd * 'e
val e: 'e
val tuple6: a: 'a -> b: 'b -> c: 'c -> d: 'd -> e: 'e -> f: 'f -> 'a * 'b * 'c * 'd * 'e * 'f
val f: 'f
val tuple7: a: 'a -> b: 'b -> c: 'c -> d: 'd -> e: 'e -> f: 'f -> g: 'g -> 'a * 'b * 'c * 'd * 'e * 'f * 'g
val g: 'g
val tuple8: a: 'a -> b: 'b -> c: 'c -> d: 'd -> e: 'e -> f: 'f -> g: 'g -> h: 'h -> 'a * 'b * 'c * 'd * 'e * 'f * 'g * 'h
val h: 'h