map transforms a value without changing the surrounding context that holds it. Give it a function from 'T to 'U, and it lifts that function so it can work on 'T inside an effect and return 'U inside the same effect. The effect decides what happens when no usable value is available; the mapping function stays ordinary, focused code. section 15.4.3
For lists, List.map applies a mapping function to every item and produces a new list of transformed items. Its signature, mapping : ('T -> 'U) -> 'T list -> 'U list, makes the two inputs explicit: a converter and the list to convert. It does not modify the original list. section 7.2.3 section 7.2.4
Convert list values
Use a small mapping function when each input item becomes one output item: let output = [ 1; 2; 3; 4 ] |> List.map (fun x -> x.ToString()) The result is a new list of strings. The pipeline keeps the data flow visible: start with values, then describe their conversion. section 7.2.3
The same pattern avoids writing separate, hand-rolled logic for common effects. Option.map runs a function when a value exists and preserves None otherwise. Result.map transforms an Ok value while preserving an Error. Task.map waits for its value, and List.map transforms every list item. In each case, map handles the effect-specific checking and rewrapping. section 15.4.3
Lift one function across effects
A normal function can be reused unchanged: let timesTwo (x:int) = $"{x} * 2 is {x * 2}" let timesTwoOptional = Option.map timesTwo let timesTwoResult = Result.map timesTwo let timesTwoList = List.map timesTwo let timesTwoTask = Task.map timesTwo Each mapped function retains its input effect while changing the value inside it. section 15.4.3
Choose map when one input value corresponds to one transformed output value inside the same effect:
- Use List.map to convert every item in a list from one shape to another. section 7.2.4
- Use Option.map, Result.map, or Task.map when the surrounding optionality, validation state, or completion state must be preserved. section 15.4.3
- Use collect, also called flatMap or SelectMany elsewhere, when each item produces a list and the result must be flattened. section 7.2.4 section 15.4.3
Do not confuse the map operation with the F# Map type. Map is an immutable dictionary-like key/value collection: adding a key returns a new map, and adding an existing key replaces its old value. The map operation, by contrast, is a transformation function such as List.map or Result.map. section 7.3.5 section 15.4.3
Table 15.3 How map appropriately behaves for each different effect (view table figure)
Compare map’s happy and unhappy paths across Option, Result, Task, and List to see how the same mapping function preserves each effect’s behavior. section 15.4.3
