Skip to content

Commit

Permalink
Moved average to the modifiers and documented. Fixed human diff defau…
Browse files Browse the repository at this point in the history 
…lt when null.
  • Loading branch information
@briannesbitt
briannesbitt committed Dec 5, 2013
1 parent cad9164 commit 03ede52
Show file tree
Hide file tree
Showing 6 changed files with 213 additions and 166 deletions.
5 changes: 5 additions & 0 deletions history.md
View file
Original file line number Diff line number Diff line change
@@ -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
Expand Down
42 changes: 36 additions & 6 deletions readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -632,6 +632,9 @@ echo $dt->diffInMinutes($dt->copy()->addSeconds(120)); // 2
// diffInYears(), diffInMonths(), diffInDays()
// diffInHours(), diffInMinutes(), diffInSeconds()
```
```php
// Carbon::average(Carbon $dt = null)
```

<a name="api-humandiff"/>
### Difference for Humans
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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()

```

<a name="api-constants"/>
Expand Down Expand Up @@ -816,4 +844,6 @@ You can view the history of the Carbon project in the [history file](https://git
<a name="about-whyname"/>
### Why the name Carbon?

Read about [Carbon Dating](http://en.wikipedia.org/wiki/Radiocarbon_dating)
Read about [Carbon Dating](http://en.wikipedia.org/wiki/Radiocarbon_dating)

![](https://cruel-carlota.pagodabox.com/55ce479cc1edc5e0cc5b4b6f9a7a9200)
14 changes: 13 additions & 1 deletion readme.src.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
```

<a name="api-humandiff"/>
### Difference for Humans
Expand Down Expand Up @@ -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}}
Expand Down Expand Up @@ -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()

```

<a name="api-constants"/>
Expand Down Expand Up @@ -856,4 +866,6 @@ You can view the history of the Carbon project in the [history file](https://git
<a name="about-whyname"/>
### Why the name Carbon?

Read about [Carbon Dating](http://en.wikipedia.org/wiki/Radiocarbon_dating)
Read about [Carbon Dating](http://en.wikipedia.org/wiki/Radiocarbon_dating)

![](https://cruel-carlota.pagodabox.com/55ce479cc1edc5e0cc5b4b6f9a7a9200)
30 changes: 15 additions & 15 deletions src/Carbon/Carbon.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down Expand Up @@ -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 ////////////////////////////
///////////////////////////////////////////////////////////////////
Expand Down Expand Up @@ -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));
}
}
24 changes: 0 additions & 24 deletions tests/DiffTest.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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();
Expand Down
Loading

0 comments on commit 03ede52

Please sign in to comment.