From 1a8d8020bd61d4f88d1d9a432bb1046b3c24861a Mon Sep 17 00:00:00 2001 From: Mark Story Date: Thu, 27 Jul 2017 22:00:30 -0400 Subject: [PATCH 1/5] Add docs for collection avg & median. Refs cakephp/cakephp#10922 --- en/appendices/3-5-migration-guide.rst | 6 +++ en/core-libraries/collections.rst | 75 +++++++++++++++++++-------- 2 files changed, 60 insertions(+), 21 deletions(-) diff --git a/en/appendices/3-5-migration-guide.rst b/en/appendices/3-5-migration-guide.rst index 0635f8bd01..f27bca12e1 100644 --- a/en/appendices/3-5-migration-guide.rst +++ b/en/appendices/3-5-migration-guide.rst @@ -175,6 +175,12 @@ cache configuration to fall back to if the engine is misconfigured (or unavailable). See :ref:`cache-configuration-fallback` for more information on configuring fallbacks. +Collection +---------- + +* ``Cake\Collection\Collection::avg()`` was added. +* ``Cake\Collection\Collection::median()`` was added. + Core ---- diff --git a/en/core-libraries/collections.rst b/en/core-libraries/collections.rst index e8cd107d00..17e5f417a7 100644 --- a/en/core-libraries/collections.rst +++ b/en/core-libraries/collections.rst @@ -53,27 +53,27 @@ List of Methods .. table:: :class: docutils internal-toc - +-----------------------+---------------------------+----------------------+---------------------+ - | :php:meth:`append` | :php:meth:`buffered` | :php:meth:`combine` | :php:meth:`compile` | - +-----------------------+---------------------------+----------------------+---------------------+ - | :php:meth:`contains` | :php:meth:`countBy` | :php:meth:`chunk` | :php:meth:`each` | - +-----------------------+---------------------------+----------------------+---------------------+ - | :php:meth:`every` | :php:meth:`extract` | :php:meth:`filter` | :php:meth:`first` | - +-----------------------+---------------------------+----------------------+---------------------+ - | :php:meth:`groupBy` | :php:meth:`indexBy` | :php:meth:`insert` | :php:meth:`isEmpty` | - +-----------------------+---------------------------+----------------------+---------------------+ - | :php:meth:`last` | :php:meth:`listNested` | :php:meth:`map` | :php:meth:`match` | - +-----------------------+---------------------------+----------------------+---------------------+ - | :php:meth:`max` | :php:meth:`min` | :php:meth:`nest` | :php:meth:`reduce` | - +-----------------------+---------------------------+----------------------+---------------------+ - | :php:meth:`reject` | :php:meth:`sample` | :php:meth:`shuffle` | :php:meth:`skip` | - +-----------------------+---------------------------+----------------------+---------------------+ - | :php:meth:`some` | :php:meth:`sortBy` | :php:meth:`stopWhen` | :php:meth:`sumOf` | - +-----------------------+---------------------------+----------------------+---------------------+ - | :php:meth:`take` | :php:meth:`through` | :php:meth:`unfold` | :php:meth:`zip` | - +-----------------------+---------------------------+----------------------+---------------------+ - | :php:meth:`transpose` | :php:meth:`chunkWithKeys` | | | - +-----------------------+---------------------------+----------------------+---------------------+ + +---------------------------------------------------+----------------------+------------------------+ + | :php:meth:`append` | :php:meth:`avg` | :php:meth:`buffered` | :php:meth:`combine` | + +---------------------------+-----------------------+----------------------+------------------------+ + | :php:meth:`compile` | :php:meth:`contains` | :php:meth:`countBy` | :php:meth:`chunk` | + +---------------------------+-----------------------+----------------------+------------------------+ + | :php:meth:`chunkWithKeys` | :php:meth:`each` | :php:meth:`every` | :php:meth:`extract` | + +---------------------------+-----------------------+----------------------+------------------------+ + | :php:meth:`filter` | :php:meth:`first` | :php:meth:`groupBy` | :php:meth:`indexBy` | + +---------------------------+-----------------------+----------------------+------------------------+ + | :php:meth:`insert` | :php:meth:`isEmpty` | :php:meth:`last` | :php:meth:`listNested` | + +---------------------------+-----------------------+----------------------+------------------------+ + | :php:meth:`map` | :php:meth:`match` | :php:meth:`max` | :php:meth:`median` | + +---------------------------+-----------------------+----------------------+------------------------+ + | :php:meth:`min` | :php:meth:`nest` | :php:meth:`reduce` | :php:meth:`reject` | + +---------------------------+-----------------------+----------------------+------------------------+ + | :php:meth:`sample` | :php:meth:`shuffle` | :php:meth:`skip` | :php:meth:`some` | + +---------------------------+-----------------------+----------------------+------------------------+ + | :php:meth:`sortBy` | :php:meth:`stopWhen` | :php:meth:`sumOf` | :php:meth:`take` | + +---------------------------+-----------------------+----------------------+------------------------+ + | :php:meth:`through` | :php:meth:`transpose` | :php:meth:`unfold` | :php:meth:`zip` | + +---------------------------+-----------------------+----------------------+------------------------+ Iterating ========= @@ -470,6 +470,39 @@ elements:: $sumOfDadAges = $collection->sumOf('dad.age'); +.. php:method:: avg($matcher = null) + +Calculate the average value of the elements in the collection. Optionally +provide a matcher path, or function to extract values to generate the average +for:: + + $items = [ + ['invoice' => ['total' => 100]], + ['invoice' => ['total' => 200]] + ]; + + // Total: 150 + $total = (new Collection($items))->avg('invoice.total'); + +.. versionadded:: 3.5.0 + +.. php:method:: median($matcher = null) + +Calculate the median value of the set of elements. Optionally provide a matcher +path, or function to extract values to generate the median for:: + + $items = [ + ['invoice' => ['total' => 400]], + ['invoice' => ['total' => 500]] + ['invoice' => ['total' => 100]] + ['invoice' => ['total' => 333]] + ['invoice' => ['total' => 200]] + ]; + // Total: 333 + $total = (new Collection($items))->median('invoice.total'); + +.. versionadded:: 3.5.0 + Grouping and Counting --------------------- From 3bceb9ffecc57189f565c946e949de41fad9a1db Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marc=20W=C3=BCrth?= Date: Fri, 28 Jul 2017 12:45:42 +0200 Subject: [PATCH 2/5] Missing commas, some mandatory --- en/core-libraries/collections.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/en/core-libraries/collections.rst b/en/core-libraries/collections.rst index 17e5f417a7..8e0a6c4f22 100644 --- a/en/core-libraries/collections.rst +++ b/en/core-libraries/collections.rst @@ -478,7 +478,7 @@ for:: $items = [ ['invoice' => ['total' => 100]], - ['invoice' => ['total' => 200]] + ['invoice' => ['total' => 200]], ]; // Total: 150 @@ -493,10 +493,10 @@ path, or function to extract values to generate the median for:: $items = [ ['invoice' => ['total' => 400]], - ['invoice' => ['total' => 500]] - ['invoice' => ['total' => 100]] - ['invoice' => ['total' => 333]] - ['invoice' => ['total' => 200]] + ['invoice' => ['total' => 500]], + ['invoice' => ['total' => 100]], + ['invoice' => ['total' => 333]], + ['invoice' => ['total' => 200]], ]; // Total: 333 $total = (new Collection($items))->median('invoice.total'); From 068629e0262755063d22d6c3aabc5201705f92b1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marc=20W=C3=BCrth?= Date: Fri, 28 Jul 2017 12:46:12 +0200 Subject: [PATCH 3/5] A set, not the set --- en/core-libraries/collections.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/core-libraries/collections.rst b/en/core-libraries/collections.rst index 8e0a6c4f22..e2530e4883 100644 --- a/en/core-libraries/collections.rst +++ b/en/core-libraries/collections.rst @@ -488,7 +488,7 @@ for:: .. php:method:: median($matcher = null) -Calculate the median value of the set of elements. Optionally provide a matcher +Calculate the median value of a set of elements. Optionally provide a matcher path, or function to extract values to generate the median for:: $items = [ From 9058a4fc52e442710e4ba55d69853f9e845234e6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marc=20W=C3=BCrth?= Date: Fri, 28 Jul 2017 12:47:40 +0200 Subject: [PATCH 4/5] Add white line --- en/core-libraries/collections.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/en/core-libraries/collections.rst b/en/core-libraries/collections.rst index e2530e4883..5cdadd43c1 100644 --- a/en/core-libraries/collections.rst +++ b/en/core-libraries/collections.rst @@ -498,6 +498,7 @@ path, or function to extract values to generate the median for:: ['invoice' => ['total' => 333]], ['invoice' => ['total' => 200]], ]; + // Total: 333 $total = (new Collection($items))->median('invoice.total'); From b5fbcba958c4f3d5098bc8ea32c77d234397dfa3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marc=20W=C3=BCrth?= Date: Fri, 28 Jul 2017 12:49:35 +0200 Subject: [PATCH 5/5] Rename variables after their function --- en/core-libraries/collections.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/en/core-libraries/collections.rst b/en/core-libraries/collections.rst index 5cdadd43c1..7ea383bc95 100644 --- a/en/core-libraries/collections.rst +++ b/en/core-libraries/collections.rst @@ -481,8 +481,8 @@ for:: ['invoice' => ['total' => 200]], ]; - // Total: 150 - $total = (new Collection($items))->avg('invoice.total'); + // Average: 150 + $average = (new Collection($items))->avg('invoice.total'); .. versionadded:: 3.5.0 @@ -499,8 +499,8 @@ path, or function to extract values to generate the median for:: ['invoice' => ['total' => 200]], ]; - // Total: 333 - $total = (new Collection($items))->median('invoice.total'); + // Median: 333 + $median = (new Collection($items))->median('invoice.total'); .. versionadded:: 3.5.0