Skip to content
This repository
Browse code

Review the docs for Enum functions

  • Loading branch information...
commit bf28eb08a5b4aca51047a5c14f888ffe0ae49d3d 1 parent 2c4f17f
Alexei Sholik authored

Showing 1 changed file with 29 additions and 25 deletions. Show diff stats Hide diff stats

  1. +29 25 lib/enum.ex
54 lib/enum.ex
@@ -16,6 +16,10 @@ defmodule Enum do
16 16
17 17 Enum.map [1,2,3], fn(x, do: x * 2)
18 18
  19 + Depending on the type of the collection, the user-provided function will
  20 + accept a certain type of argument. For dicts, the argument is always a
  21 + { key, value } tuple.
  22 +
19 23 You can also use a custom iteration function for any collection by passing it
20 24 along with the head of iteration:
21 25
@@ -24,26 +28,14 @@ defmodule Enum do
24 28
25 29 ## The protocol
26 30
27   - When `Enum.<function>` is invoked without the iteration function,
28   - it invokes `Enum.Iterator.iterator(collection)` on the
29   - given collection in order to retrieve the iterator
30   - for that collection. You can implement the protocol for any
31   - data type you wish. Elixir ships with a default iterator
32   - for lists, implemented as follows:
33   -
34   - defimpl Enum.Iterator, for: List do
35   - def iterator(list), do: { iterate(&1), iterate(list) }
36   -
37   - defp iterate([h|t]) do
38   - { h, t }
39   - end
40   -
41   - defp iterate([]) do
42   - :stop
43   - end
44   - end
  31 + When `Enum.<function>` is invoked without the iteration function, it invokes
  32 + `Enum.Iterator.iterator(collection)` on the given collection in order to
  33 + retrieve the iterator for that collection. Some functions expect the
  34 + collection to define an ordering for its elements. Those functions use
  35 + `Enum.Iterator.ordered_iterator(collection)` instead. You can implement the
  36 + protocol for any data type you wish. Elixir ships with a default iterator for
  37 + lists and dicts.
45 38
46   - The `:stop` marks the end of iteration loop.
47 39 """
48 40
49 41 @doc """
@@ -77,7 +69,7 @@ defmodule Enum do
77 69
78 70 @doc """
79 71 Invokes the given `fun` for each item in the `collection` and returns true if
80   - at least one invocation returns true. Returns false otherwise.
  72 + at least one invocation returns true. Returns false otherwise.
81 73
82 74 ## Examples
83 75
@@ -104,7 +96,8 @@ defmodule Enum do
104 96 end
105 97
106 98 @doc """
107   - Drops the first `count` items from the collection.
  99 + Drops the first `count` items from the collection. Expects an ordered
  100 + collection.
108 101
109 102 ## Examples
110 103
@@ -124,6 +117,7 @@ defmodule Enum do
124 117
125 118 @doc """
126 119 Drops items at the beginning of `collection` while `fun` returns true.
  120 + Expects an ordered collection.
127 121
128 122 ## Examples
129 123
@@ -294,6 +288,8 @@ defmodule Enum do
294 288 All items in the collection must be convertible
295 289 to binary, otherwise an error is raised.
296 290
  291 + Expects an ordered collection.
  292 +
297 293 ## Examples
298 294
299 295 Enum.join([1,2,3]) #=> "123"
@@ -378,6 +374,9 @@ defmodule Enum do
378 374 the first element is the mapped collection and the second
379 375 one is the final accumulator.
380 376
  377 + For dicts, the first tuple element has to be a { key, value }
  378 + tuple itself.
  379 +
381 380 ## Examples
382 381
383 382 Enum.map_reduce [1, 2, 3], 0, fn(x, acc, do: { x * 2, x + acc })
@@ -398,7 +397,7 @@ defmodule Enum do
398 397 end
399 398
400 399 @doc """
401   - Partitions `collection` into two lists where the first one contains elements
  400 + Partitions `collection` into two where the first one contains elements
402 401 for which `fun` returns a truthy value, and the second one -- for which `fun`
403 402 returns false or nil.
404 403
@@ -442,8 +441,8 @@ defmodule Enum do
442 441 end
443 442
444 443 @doc """
445   - Splits the enumerable into two lists, leaving `count` elements in the first
446   - one.
  444 + Splits the enumerable into two collections, leaving `count` elements in the
  445 + first one. Expects an ordered collection.
447 446
448 447 ## Examples
449 448
@@ -463,6 +462,7 @@ defmodule Enum do
463 462
464 463 @doc """
465 464 Splits `collection` at the first element, for which `fun` returns true.
  465 + Expects an ordered collection.
466 466
467 467 ## Examples
468 468
@@ -479,7 +479,8 @@ defmodule Enum do
479 479 end
480 480
481 481 @doc """
482   - Takes the first `count` items from the collection.
  482 + Takes the first `count` items from the collection. Expects an ordered
  483 + collection.
483 484
484 485 ## Examples
485 486
@@ -499,6 +500,7 @@ defmodule Enum do
499 500
500 501 @doc """
501 502 Takes the items at the beginning of `collection` while `fun` returns true.
  503 + Expects an ordered collection.
502 504
503 505 ## Examples
504 506
@@ -862,6 +864,8 @@ defimpl Enum.Iterator, for: List do
862 864 #
863 865 # `ctor` is a constructor function that takes a list of elements and
864 866 # produces a new enumerable of the same type as the initial one.
  867 + #
  868 + # The :stop atom is mandatory, it signifies the end of the iteration.
865 869 { :stop, ctor, nil}
866 870 end
867 871 end

0 comments on commit bf28eb0

Please sign in to comment.
Something went wrong with that request. Please try again.