You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/fsharp/tour.md
+63-30Lines changed: 63 additions & 30 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -29,47 +29,63 @@ The quickest way to run these code samples is to use [F# Interactive](tutorials/
29
29
30
30
The most fundamental pieces of any F# program are ***functions*** organized into ***modules***. [Functions](language-reference/functions/index.md) perform work on inputs to produce outputs, and they are organized under [Modules](language-reference/modules.md), which are the primary way you group things in F#. They are defined using the [`let` binding](language-reference/functions/let-bindings.md), which give the function a name and define its arguments.
`let` bindings are also how you bind a value to a name, similar to a variable in other languages. `let` bindings are ***immutable*** by default, which means that once a value or function is bound to a name, it cannot be changed in-place. This is in contrast to variables in other languages, which are ***mutable***, meaning their values can be changed at any point in time. If you require a mutable binding, you can use `let mutable ...` syntax.
[Tuples](language-reference/tuples.md) are a big deal in F#. They are a grouping of unnamed, but ordered values, that can be treated as values themselves. Think of them as values which are aggregated from other values. They have many uses, such as conveniently returning multiple values from a function, or grouping values for some ad-hoc convenience.
It's important to note that because `struct` tuples are value types, they are cannot be implicitly converted to reference tuples, or vice versa. You must explicitly convert between a reference and struct tuple.
65
+
66
+
## Pipelines and Composition
67
+
68
+
Pipe operators (`|>`, `<|`, `||>`, `<||`, `|||>`, `<|||`) and composition operators (`>>` and `<<`) are used extensively when processing data in F#. These operators are functions which allow you to establish "pipelines" of functions in a flexible manner. The following walks though how you could take advantage of these operators to build a simple functional pipeline.
The above sample made use of many features of F#, including list processing functions, first-class functions, and [partial application](language-reference/functions/index.md#partial-application-of-arguments). Although a deep understanding of each of those concepts can become somewhat advanced, it should be clear how easily functions can be used to process data when building pipelines.
57
73
58
74
## Lists, Arrays, and Sequences
59
75
60
76
Lists, Arrays, and Sequences are three primary collection types in the F# core library.
61
77
62
78
[Lists](language-reference/lists.md) are ordered, immutable collections of elements of the same type. They are singly-linked lists, which means they are meant for enumeration, but a poor choice for random access and concatenation if they're large. This in contrast to Lists in other popular languages, which typically do not use a singly-linked list to represent Lists.
[Arrays](language-reference/arrays.md) are fixed-size, *mutable* collections of elements of the same type. They support fast random access of elements, and are faster than F# lists because they are just contiguous blocks of memory.
[Sequences](language-reference/sequences.md) are a logical series of elements, all of the same type. These are a more general type than Lists and Arrays, capable of being your "view" into any logical series of elements. They also stand out because can be ***lazy***, which means that elements can be computed only when they are needed.
F# also has full support for Tail Call Optimization, which is a way to optimize recursive calls so that they are just as fast as a loop construct.
84
100
@@ -88,53 +104,70 @@ Record and Union types are two fundamental data types used in F# code, and are g
88
104
89
105
[Records](language-reference/records.md) are an aggregate of named values, with optional members (such as methods). If you're familiar with C# or Java, then these should feel similar to POCOs or POJOs - just with structural equality and less ceremony.
[Discriminated Unions (DUs)](language-reference/discriminated-unions.md) are values which could be a number of named forms or cases. Data stored in the type can be one of several distinct values.
You can also use DUs as *Single-Case Discriminated Unions*, to help with domain modeling over primitive types. Often times, strings and other primitive types are used to represent something, and are thus given a particular meaning. However, using only the primitive representation of the data can result in mistakenly assigning an incorrect value! Representing each type of information as a distinct single-case union can enforce correctness in this scenario.
As the above sample demonstrates, to get the underlying value in a single-case Discriminated Union, you must explicitly unwrap it.
122
+
123
+
Additionally, DUs also support recursive definitions, allowing you to easily represent trees and inherently recursive data. For example, here's how you can represent a Binary Search Tree with `exists` and `insert` functions.
92
124
93
-
[Discriminated Unions](language-reference/discriminated-unions.md) are values which could be a number of named forms or cases. Data stored in the type can be one of several distinct values.
Because DUs allow you to represent the recursive structure of the tree in the data type, operating on this recursive structure is straightforward and guarantees correctness. It is also supported in pattern matching, as shown below.
96
128
97
-
You can also use Unions as *single-case unions*, to help with domain modeling over primitive types. Often times, strings and other primitive types are used to represent types of information that shouldn't be interchangeable. However, using only the string representation can lead to that mistake quite easily! Representing each type of information as a distinct single-case union can enforce correctness in this scenario.
129
+
Additionally, you can represent DUs as `struct`s with the `[<Struct>]` attribute:
Additionally, Discriminated Unions also support recursive definitions, allowing you to easily represent trees and inherently recursive data. For example, here's how you can represent a Binary Search Tree with `exists` and `insert` functions.
133
+
However, there are two key things to keep in mind when doing so:
2. A struct DU must have unique names for each of its cases.
104
137
105
-
Because Discriminated Unions allow you to represent the recursive structure of the tree in the data type, operating on this recursive structure is straightforward and guarantees correctness. It is also supported in pattern matching, as shown below.
138
+
Failure to follow the above will result in a compilation error.
106
139
107
140
## Pattern Matching
108
141
109
142
[Pattern Matching](language-reference/pattern-matching.md) is the F# language feature which enables correctness for operating on F# types. In the above samples, you probably noticed quite a bit of `match x with ...` syntax. This construct allows the compiler, which can understand the "shape" of data types, to force you to account for all possible cases when using a data type through what is known as Exhaustive Pattern Matching. This is incredibly powerful for correctness, and can be cleverly used to "lift" what would normally be a runtime concern into compile-time.
You can also use the shorthand `function` construct for pattern matching, which is useful when you're writing functions which make use of [Partial Application](language-reference/functions/index.md#partial-application-of-arguments):
Something you may have noticed is the use of the `_` pattern. This is known as the [Wildcard Pattern](language-reference/pattern-matching.md#wildcard-pattern), which is a way of saying "I don't care what something is". Although convenient, you can accidentally bypass Exhaustive Pattern Matching and no longer benefit from compile-time enforcements if you aren't careful in using `_`.
150
+
Something you may have noticed is the use of the `_` pattern. This is known as the [Wildcard Pattern](language-reference/pattern-matching.md#wildcard-pattern), which is a way of saying "I don't care what something is". Although convenient, you can accidentally bypass Exhaustive Pattern Matching and no longer benefit from compile-time enforcements if you aren't careful in using `_`. It is best used when you don't care about certain pieces of a decomposed type when pattern matching, or the final clause when you have enumerated all meaningful cases in a pattern matching expression.
118
151
119
152
[Active Patterns](language-reference/active-patterns.md) are another powerful construct to use with pattern matching. They allow you to partition input data into custom forms, decomposing them at the pattern match call site. They can also be parameterized, thus allowing to define the partition as a function. Expanding the previous example to support Active Patterns looks something like this:
One special case of Discriminated Union types is the Option Type, which is so useful that it's a part of the F# core library.
126
159
127
-
[The Option Type](language-reference/options.md) is a type which represents one of two cases: a value, or nothing at all. It is used in any scenario where a value may or may not result from a particular operation. This then forces you to account for both cases, making it a compile-time concern rather than a runtime concern. These are often used in APIs where `null` is used to represent "nothing" instead, thus eliminating the need to worry about `NulReferenceException` in many circumstances.
160
+
[The Option Type](language-reference/options.md) is a type which represents one of two cases: a value, or nothing at all. It is used in any scenario where a value may or may not result from a particular operation. This then forces you to account for both cases, making it a compile-time concern rather than a runtime concern. These are often used in APIs where `null` is used to represent "nothing" instead, thus eliminating the need to worry about `NullReferenceException` in many circumstances.
One unique feature of F#'s type system is the ability to provide context for numeric literals through Units of Measure.
134
167
135
168
[Units of Measure](language-reference/units-of-measure.md) allow you to associate a numeric type to a unit, such as Meters, and have functions perform work on units rather than numeric literals. This enables the compiler to verify that the types of numeric literals passed in make sense under a certain context, and eliminate runtime errors associated with that kind of work.
The F# Core library defines many SI unit types and unit conversions. To learn more, check out the [Microsoft.FSharp.Data.UnitSystems.SI Namespace](https://msdn.microsoft.com/visualfsharpdocs/conceptual/microsoft.fsharp.data.unitsystems.si-namespace-%5bfsharp%5d).
140
173
@@ -144,15 +177,15 @@ F# also has full support for .NET classes, [Interfaces](language-reference/inter
144
177
145
178
[Classes](language-reference/classes.md) are types that represent .NET objects, which can have properties, methods, and events as its [Members](language-reference/members/index.md).
0 commit comments