diff --git a/history.md b/history.md
index 909ab4ad45..a5d7ae4395 100644
--- a/history.md
+++ b/history.md
@@ -1,3 +1,8 @@
+1.7.0 / 2013-12-04
+==================
+* Added startOfYear() / endOfYear() (thanks @semalead)
+* Added average() (thanks @semalead)
+
1.6.0 / 2013-11-23
==================
* Fixed "Cannot access property ::$toStringFormat" when extending Carbon and type juggling to a string occurs
diff --git a/readme.md b/readme.md
index a341d261ab..d70bef9ea5 100644
--- a/readme.md
+++ b/readme.md
@@ -177,13 +177,13 @@ To accompany `now()`, a few other static instantiation helpers exist to create w
```php
$now = Carbon::now();
-echo $now; // 2013-11-21 16:05:46
+echo $now; // 2013-12-04 23:07:48
$today = Carbon::today();
-echo $today; // 2013-11-21 00:00:00
+echo $today; // 2013-12-04 00:00:00
$tomorrow = Carbon::tomorrow('Europe/London');
-echo $tomorrow; // 2013-11-22 00:00:00
+echo $tomorrow; // 2013-12-06 00:00:00
$yesterday = Carbon::yesterday();
-echo $yesterday; // 2013-11-20 00:00:00
+echo $yesterday; // 2013-12-03 00:00:00
```
The next group of static helpers are the `createXXX()` helpers. Most of the static `create` functions allow you to provide as many or as few arguments as you want and will provide default values for all others. Generally default values are the current date, time or timezone. Higher values will wrap appropriately but invalid values will throw an `InvalidArgumentException` with an informative message. The message is obtained from an [DateTime::getLastErrors()](http://php.net/manual/en/datetime.getlasterrors.php) call.
@@ -261,7 +261,7 @@ echo Carbon::parse('now'); // 2001-05-21 12:00:00
var_dump(Carbon::hasTestNow()); // bool(true)
Carbon::setTestNow(); // clear the mock
var_dump(Carbon::hasTestNow()); // bool(false)
-echo Carbon::now(); // 2013-11-21 16:05:46
+echo Carbon::now(); // 2013-12-04 23:07:48
```
A more meaning full example:
@@ -632,6 +632,9 @@ echo $dt->diffInMinutes($dt->copy()->addSeconds(120)); // 2
// diffInYears(), diffInMonths(), diffInDays()
// diffInHours(), diffInMinutes(), diffInSeconds()
```
+```php
+// Carbon::average(Carbon $dt = null)
+```
### Difference for Humans
@@ -678,6 +681,8 @@ echo Carbon::now()->subDays(24)->diffForHumans(); // 3 weeks ago
These group of methods perform helpful modifications to the current instance. Most of them are self explanatory from their names... or at least should be. You'll also notice that the startOfXXX(), next() and previous() methods set the time to 00:00:00 and the endOfXXX() methods set the time to 23:59:59.
+The only one slightly different is the `average()` function. It moves your instance to the middle date between itself and the provided Carbon argument.
+
```php
$dt = Carbon::create(2012, 1, 31, 12, 0, 0);
echo $dt->startOfDay(); // 2012-01-31 00:00:00
@@ -691,6 +696,24 @@ echo $dt->startOfMonth(); // 2012-01-01 00:00:00
$dt = Carbon::create(2012, 1, 31, 12, 0, 0);
echo $dt->endOfMonth(); // 2012-01-31 23:59:59
+$dt = Carbon::create(2012, 1, 31, 12, 0, 0);
+echo $dt->startOfYear(); // 2012-01-01 00:00:00
+
+$dt = Carbon::create(2012, 1, 31, 12, 0, 0);
+echo $dt->endOfYear(); // 2012-12-31 23:59:59
+
+$dt = Carbon::create(2012, 1, 31, 12, 0, 0);
+echo $dt->startOfDecade(); // 2010-01-01 00:00:00
+
+$dt = Carbon::create(2012, 1, 31, 12, 0, 0);
+echo $dt->endOfDecade(); // 2019-12-31 23:59:59
+
+$dt = Carbon::create(2012, 1, 31, 12, 0, 0);
+echo $dt->startOfCentury(); // 2000-01-01 00:00:00
+
+$dt = Carbon::create(2012, 1, 31, 12, 0, 0);
+echo $dt->endOfCentury(); // 2099-12-31 23:59:59
+
$dt = Carbon::create(2012, 1, 31, 12, 0, 0);
echo $dt->startOfWeek(); // 2012-01-30 00:00:00
var_dump($dt->dayOfWeek == Carbon::MONDAY); // bool(true) : ISO8601 week starts on Monday
@@ -713,10 +736,15 @@ var_dump($dt->dayOfWeek == Carbon::WEDNESDAY); // bool(true)
$dt = Carbon::create(2012, 1, 1, 12, 0, 0);
echo $dt->previous(); // 2011-12-25 00:00:00
+$start = Carbon::create(2014, 1, 1, 0, 0, 0);
+$end = Carbon::create(2014, 1, 30, 0, 0, 0);
+echo $start->average($end); // 2014-01-15 12:00:00
+
// others that are defined that are similar
// firstOfMonth(), lastOfMonth(), nthOfMonth()
// firstOfQuarter(), lastOfQuarter(), nthOfQuarter()
// firstOfYear(), lastOfYear(), nthOfYear()
+
```
@@ -816,4 +844,6 @@ You can view the history of the Carbon project in the [history file](https://git
### Why the name Carbon?
-Read about [Carbon Dating](http://en.wikipedia.org/wiki/Radiocarbon_dating)
\ No newline at end of file
+Read about [Carbon Dating](http://en.wikipedia.org/wiki/Radiocarbon_dating)
+
+
\ No newline at end of file
diff --git a/readme.src.md b/readme.src.md
index b6fa66d1ab..e1b99ad2bf 100644
--- a/readme.src.md
+++ b/readme.src.md
@@ -652,6 +652,9 @@ These functions always return the **total difference** expressed in the specifie
// diffInYears(), diffInMonths(), diffInDays()
// diffInHours(), diffInMinutes(), diffInSeconds()
```
+```php
+// Carbon::average(Carbon $dt = null)
+```
### Difference for Humans
@@ -698,6 +701,8 @@ This method will add a phrase after the difference value relative to the instanc
These group of methods perform helpful modifications to the current instance. Most of them are self explanatory from their names... or at least should be. You'll also notice that the startOfXXX(), next() and previous() methods set the time to 00:00:00 and the endOfXXX() methods set the time to 23:59:59.
+The only one slightly different is the `average()` function. It moves your instance to the middle date between itself and the provided Carbon argument.
+
```php
{{::lint($dt = Carbon::create(2012, 1, 31, 12, 0, 0);/*pad(40)*/)}}
{{modifier1::exec(echo $dt->startOfDay();/*pad(50)*/)}} // {{modifier1_eval}}
@@ -751,10 +756,15 @@ These group of methods perform helpful modifications to the current instance. M
{{::lint($dt = Carbon::create(2012, 1, 1, 12, 0, 0);)}}
{{modifier14::exec(echo $dt->previous();/*pad(50)*/)}} // {{modifier14_eval}}
+{{::lint($start = Carbon::create(2014, 1, 1, 0, 0, 0);)}}
+{{::lint($end = Carbon::create(2014, 1, 30, 0, 0, 0);)}}
+{{modifierAverage::exec(echo $start->average($end);/*pad(50)*/)}} // {{modifierAverage_eval}}
+
// others that are defined that are similar
// firstOfMonth(), lastOfMonth(), nthOfMonth()
// firstOfQuarter(), lastOfQuarter(), nthOfQuarter()
// firstOfYear(), lastOfYear(), nthOfYear()
+
```
@@ -856,4 +866,6 @@ You can view the history of the Carbon project in the [history file](https://git
### Why the name Carbon?
-Read about [Carbon Dating](http://en.wikipedia.org/wiki/Radiocarbon_dating)
\ No newline at end of file
+Read about [Carbon Dating](http://en.wikipedia.org/wiki/Radiocarbon_dating)
+
+
\ No newline at end of file
diff --git a/src/Carbon/Carbon.php b/src/Carbon/Carbon.php
index 5e44c1bee3..829228e722 100644
--- a/src/Carbon/Carbon.php
+++ b/src/Carbon/Carbon.php
@@ -1672,7 +1672,7 @@ public function diffForHumans(Carbon $other = null)
$isNow = $other === null;
if ($isNow) {
- $other = self::now();
+ $other = static::now($this->tz);
}
$isFuture = $this->gt($other);
@@ -1722,20 +1722,6 @@ public function diffForHumans(Carbon $other = null)
return $txt . ' before';
}
- /**
- * Get the average of two dates
- *
- * @param Carbon $dt
- *
- * @return Carbon
- */
- public function average(Carbon $dt = null)
- {
- $dt = ($dt === null) ? static::now($this->tz) : $dt;
-
- return $this->addSeconds(intval($this->diffInSeconds($dt, false) / 2));
- }
-
///////////////////////////////////////////////////////////////////
//////////////////////////// MODIFIERS ////////////////////////////
///////////////////////////////////////////////////////////////////
@@ -2090,4 +2076,18 @@ public function nthOfYear($nth, $dayOfWeek)
return $this->modify($dt);
}
+
+ /**
+ * Modify the current instance to the average of a given instance (default now) and the current instance.
+ *
+ * @param Carbon $dt
+ *
+ * @return Carbon
+ */
+ public function average(Carbon $dt = null)
+ {
+ $dt = ($dt === null) ? static::now($this->tz) : $dt;
+
+ return $this->addSeconds(intval($this->diffInSeconds($dt, false) / 2));
+ }
}
diff --git a/tests/DiffTest.php b/tests/DiffTest.php
index 9563011911..c34c8924bd 100644
--- a/tests/DiffTest.php
+++ b/tests/DiffTest.php
@@ -396,30 +396,6 @@ public function testDiffForHumansNowAndFutureYears()
$this->assertSame('2 years from now', $d->diffForHumans());
}
- public function testAverageIsFluid()
- {
- $dt = Carbon::now()->average();
- $this->assertTrue($dt instanceof Carbon);
- }
- public function testAverageFromSame()
- {
- $dt1 = Carbon::create(2000, 1, 31, 2, 3, 4);
- $dt2 = Carbon::create(2000, 1, 31, 2, 3, 4)->average($dt1);
- $this->assertCarbon($dt2, 2000, 1, 31, 2, 3, 4);
- }
- public function testAverageFromGreater()
- {
- $dt1 = Carbon::create(2000, 1, 1, 1, 1, 1);
- $dt2 = Carbon::create(2009, 12, 31, 23, 59, 59)->average($dt1);
- $this->assertCarbon($dt2, 2004, 12, 31, 12, 30, 30);
- }
- public function testAverageFromLower()
- {
- $dt1 = Carbon::create(2009, 12, 31, 23, 59, 59);
- $dt2 = Carbon::create(2000, 1, 1, 1, 1, 1)->average($dt1);
- $this->assertCarbon($dt2, 2004, 12, 31, 12, 30, 30);
- }
-
public function testDiffForHumansOtherAndSecond()
{
$d = Carbon::now()->addSecond();
diff --git a/tests/StartEndOfTest.php b/tests/StartEndOfTest.php
index f9fd9e7e97..bb2a043e3b 100644
--- a/tests/StartEndOfTest.php
+++ b/tests/StartEndOfTest.php
@@ -42,26 +42,26 @@ public function testStartOfMonthFromLastDay()
$this->assertCarbon($dt, 2000, 1, 1, 0, 0, 0);
}
- public function testStartOfYearIsFluid()
- {
- $dt = Carbon::now();
- $this->assertTrue($dt->startOfYear() instanceof Carbon);
- }
- public function testStartOfYearFromNow()
- {
- $dt = Carbon::now()->startOfYear();
- $this->assertCarbon($dt, $dt->year, 1, 1, 0, 0, 0);
- }
- public function testStartOfYearFromFirstDay()
- {
- $dt = Carbon::create(2000, 1, 1, 1, 1, 1)->startOfYear();
- $this->assertCarbon($dt, 2000, 1, 1, 0, 0, 0);
- }
- public function testStartOfYearFromLastDay()
- {
- $dt = Carbon::create(2000, 12, 31, 23, 59, 59)->startOfYear();
- $this->assertCarbon($dt, 2000, 1, 1, 0, 0, 0);
- }
+ public function testStartOfYearIsFluid()
+ {
+ $dt = Carbon::now();
+ $this->assertTrue($dt->startOfYear() instanceof Carbon);
+ }
+ public function testStartOfYearFromNow()
+ {
+ $dt = Carbon::now()->startOfYear();
+ $this->assertCarbon($dt, $dt->year, 1, 1, 0, 0, 0);
+ }
+ public function testStartOfYearFromFirstDay()
+ {
+ $dt = Carbon::create(2000, 1, 1, 1, 1, 1)->startOfYear();
+ $this->assertCarbon($dt, 2000, 1, 1, 0, 0, 0);
+ }
+ public function testStartOfYearFromLastDay()
+ {
+ $dt = Carbon::create(2000, 12, 31, 23, 59, 59)->startOfYear();
+ $this->assertCarbon($dt, 2000, 1, 1, 0, 0, 0);
+ }
public function testEndOfMonthIsFluid()
{
@@ -79,108 +79,132 @@ public function testEndOfMonthFromLastDay()
$this->assertCarbon($dt, 2000, 1, 31, 23, 59, 59);
}
- public function testEndOfYearIsFluid()
- {
- $dt = Carbon::now();
- $this->assertTrue($dt->endOfYear() instanceof Carbon);
- }
- public function testEndOfYearFromNow()
- {
- $dt = Carbon::now()->endOfYear();
- $this->assertCarbon($dt, $dt->year, 12, 31, 23, 59, 59);
- }
- public function testEndOfYearFromFirstDay()
- {
- $dt = Carbon::create(2000, 1, 1, 1, 1, 1)->endOfYear();
- $this->assertCarbon($dt, 2000, 12, 31, 23, 59, 59);
- }
- public function testEndOfYearFromLastDay()
- {
- $dt = Carbon::create(2000, 12, 31, 23, 59, 59)->endOfYear();
- $this->assertCarbon($dt, 2000, 12, 31, 23, 59, 59);
- }
+ public function testEndOfYearIsFluid()
+ {
+ $dt = Carbon::now();
+ $this->assertTrue($dt->endOfYear() instanceof Carbon);
+ }
+ public function testEndOfYearFromNow()
+ {
+ $dt = Carbon::now()->endOfYear();
+ $this->assertCarbon($dt, $dt->year, 12, 31, 23, 59, 59);
+ }
+ public function testEndOfYearFromFirstDay()
+ {
+ $dt = Carbon::create(2000, 1, 1, 1, 1, 1)->endOfYear();
+ $this->assertCarbon($dt, 2000, 12, 31, 23, 59, 59);
+ }
+ public function testEndOfYearFromLastDay()
+ {
+ $dt = Carbon::create(2000, 12, 31, 23, 59, 59)->endOfYear();
+ $this->assertCarbon($dt, 2000, 12, 31, 23, 59, 59);
+ }
- public function testStartOfDecadeIsFluid()
- {
- $dt = Carbon::now();
- $this->assertTrue($dt->startOfDecade() instanceof Carbon);
- }
- public function testStartOfDecadeFromNow()
- {
- $dt = Carbon::now()->startOfDecade();
- $this->assertCarbon($dt, $dt->year - $dt->year % 10, 1, 1, 0, 0, 0);
- }
- public function testStartOfDecadeFromFirstDay()
- {
- $dt = Carbon::create(2000, 1, 1, 1, 1, 1)->startOfDecade();
- $this->assertCarbon($dt, 2000, 1, 1, 0, 0, 0);
- }
- public function testStartOfDecadeFromLastDay()
- {
- $dt = Carbon::create(2009, 12, 31, 23, 59, 59)->startOfDecade();
- $this->assertCarbon($dt, 2000, 1, 1, 0, 0, 0);
- }
+ public function testStartOfDecadeIsFluid()
+ {
+ $dt = Carbon::now();
+ $this->assertTrue($dt->startOfDecade() instanceof Carbon);
+ }
+ public function testStartOfDecadeFromNow()
+ {
+ $dt = Carbon::now()->startOfDecade();
+ $this->assertCarbon($dt, $dt->year - $dt->year % 10, 1, 1, 0, 0, 0);
+ }
+ public function testStartOfDecadeFromFirstDay()
+ {
+ $dt = Carbon::create(2000, 1, 1, 1, 1, 1)->startOfDecade();
+ $this->assertCarbon($dt, 2000, 1, 1, 0, 0, 0);
+ }
+ public function testStartOfDecadeFromLastDay()
+ {
+ $dt = Carbon::create(2009, 12, 31, 23, 59, 59)->startOfDecade();
+ $this->assertCarbon($dt, 2000, 1, 1, 0, 0, 0);
+ }
- public function testEndOfDecadeIsFluid()
- {
- $dt = Carbon::now();
- $this->assertTrue($dt->endOfDecade() instanceof Carbon);
- }
- public function testEndOfDecadeFromNow()
- {
- $dt = Carbon::now()->endOfDecade();
- $this->assertCarbon($dt, $dt->year - $dt->year % 10 + 9, 12, 31, 23, 59, 59);
- }
- public function testEndOfDecadeFromFirstDay()
- {
- $dt = Carbon::create(2000, 1, 1, 1, 1, 1)->endOfDecade();
- $this->assertCarbon($dt, 2009, 12, 31, 23, 59, 59);
- }
- public function testEndOfDecadeFromLastDay()
- {
- $dt = Carbon::create(2009, 12, 31, 23, 59, 59)->endOfDecade();
- $this->assertCarbon($dt, 2009, 12, 31, 23, 59, 59);
- }
+ public function testEndOfDecadeIsFluid()
+ {
+ $dt = Carbon::now();
+ $this->assertTrue($dt->endOfDecade() instanceof Carbon);
+ }
+ public function testEndOfDecadeFromNow()
+ {
+ $dt = Carbon::now()->endOfDecade();
+ $this->assertCarbon($dt, $dt->year - $dt->year % 10 + 9, 12, 31, 23, 59, 59);
+ }
+ public function testEndOfDecadeFromFirstDay()
+ {
+ $dt = Carbon::create(2000, 1, 1, 1, 1, 1)->endOfDecade();
+ $this->assertCarbon($dt, 2009, 12, 31, 23, 59, 59);
+ }
+ public function testEndOfDecadeFromLastDay()
+ {
+ $dt = Carbon::create(2009, 12, 31, 23, 59, 59)->endOfDecade();
+ $this->assertCarbon($dt, 2009, 12, 31, 23, 59, 59);
+ }
+
+ public function testStartOfCenturyIsFluid()
+ {
+ $dt = Carbon::now();
+ $this->assertTrue($dt->startOfCentury() instanceof Carbon);
+ }
+ public function testStartOfCenturyFromNow()
+ {
+ $dt = Carbon::now()->startOfCentury();
+ $this->assertCarbon($dt, $dt->year - $dt->year % 100, 1, 1, 0, 0, 0);
+ }
+ public function testStartOfCenturyFromFirstDay()
+ {
+ $dt = Carbon::create(2000, 1, 1, 1, 1, 1)->startOfCentury();
+ $this->assertCarbon($dt, 2000, 1, 1, 0, 0, 0);
+ }
+ public function testStartOfCenturyFromLastDay()
+ {
+ $dt = Carbon::create(2009, 12, 31, 23, 59, 59)->startOfCentury();
+ $this->assertCarbon($dt, 2000, 1, 1, 0, 0, 0);
+ }
- public function testStartOfCenturyIsFluid()
- {
- $dt = Carbon::now();
- $this->assertTrue($dt->startOfCentury() instanceof Carbon);
- }
- public function testStartOfCenturyFromNow()
- {
- $dt = Carbon::now()->startOfCentury();
- $this->assertCarbon($dt, $dt->year - $dt->year % 100, 1, 1, 0, 0, 0);
- }
- public function testStartOfCenturyFromFirstDay()
- {
- $dt = Carbon::create(2000, 1, 1, 1, 1, 1)->startOfCentury();
- $this->assertCarbon($dt, 2000, 1, 1, 0, 0, 0);
- }
- public function testStartOfCenturyFromLastDay()
- {
- $dt = Carbon::create(2009, 12, 31, 23, 59, 59)->startOfCentury();
- $this->assertCarbon($dt, 2000, 1, 1, 0, 0, 0);
- }
+ public function testEndOfCenturyIsFluid()
+ {
+ $dt = Carbon::now();
+ $this->assertTrue($dt->endOfCentury() instanceof Carbon);
+ }
+ public function testEndOfCenturyFromNow()
+ {
+ $dt = Carbon::now()->endOfCentury();
+ $this->assertCarbon($dt, $dt->year - $dt->year % 100 + 99, 12, 31, 23, 59, 59);
+ }
+ public function testEndOfCenturyFromFirstDay()
+ {
+ $dt = Carbon::create(2000, 1, 1, 1, 1, 1)->endOfCentury();
+ $this->assertCarbon($dt, 2099, 12, 31, 23, 59, 59);
+ }
+ public function testEndOfCenturyFromLastDay()
+ {
+ $dt = Carbon::create(2099, 12, 31, 23, 59, 59)->endOfCentury();
+ $this->assertCarbon($dt, 2099, 12, 31, 23, 59, 59);
+ }
- public function testEndOfCenturyIsFluid()
- {
- $dt = Carbon::now();
- $this->assertTrue($dt->endOfCentury() instanceof Carbon);
- }
- public function testEndOfCenturyFromNow()
- {
- $dt = Carbon::now()->endOfCentury();
- $this->assertCarbon($dt, $dt->year - $dt->year % 100 + 99, 12, 31, 23, 59, 59);
- }
- public function testEndOfCenturyFromFirstDay()
- {
- $dt = Carbon::create(2000, 1, 1, 1, 1, 1)->endOfCentury();
- $this->assertCarbon($dt, 2099, 12, 31, 23, 59, 59);
- }
- public function testEndOfCenturyFromLastDay()
- {
- $dt = Carbon::create(2099, 12, 31, 23, 59, 59)->endOfCentury();
- $this->assertCarbon($dt, 2099, 12, 31, 23, 59, 59);
- }
+ public function testAverageIsFluid()
+ {
+ $dt = Carbon::now()->average();
+ $this->assertTrue($dt instanceof Carbon);
+ }
+ public function testAverageFromSame()
+ {
+ $dt1 = Carbon::create(2000, 1, 31, 2, 3, 4);
+ $dt2 = Carbon::create(2000, 1, 31, 2, 3, 4)->average($dt1);
+ $this->assertCarbon($dt2, 2000, 1, 31, 2, 3, 4);
+ }
+ public function testAverageFromGreater()
+ {
+ $dt1 = Carbon::create(2000, 1, 1, 1, 1, 1);
+ $dt2 = Carbon::create(2009, 12, 31, 23, 59, 59)->average($dt1);
+ $this->assertCarbon($dt2, 2004, 12, 31, 12, 30, 30);
+ }
+ public function testAverageFromLower()
+ {
+ $dt1 = Carbon::create(2009, 12, 31, 23, 59, 59);
+ $dt2 = Carbon::create(2000, 1, 1, 1, 1, 1)->average($dt1);
+ $this->assertCarbon($dt2, 2004, 12, 31, 12, 30, 30);
+ }
}