JavaScript equivalent of Carbon date and time manipulation library.
You can install the package via npm:
npm install @bjnstnkvc/carbon
and then import it into your project
import { Carbon } from '@bjnstnkvc/carbon';
You can install the package via jsDelivr CDN:
<script src="https://cdn.jsdelivr.net/npm/@bjnstnkvc/carbon/lib/main.min.js"></script>
Easily create, manipulate, and interact with date and time objects using Carbon's intuitive API.
Create new Carbon instance.
- date (optional) - A string representing the date. Defaults to
null
. - timezone (optional) - A string representing the timezone. Defaults to
null
.
const carbon = new Carbon('2024-03-14');
console.log(carbon); // 2024-03-14 01:00:00.000 UTC (+01:00)
const carbon = new Carbon('2024-03-14', 'UTC');
console.log(carbon); // 2024-03-14 00:00:00.000 UTC (+00:00)
If the date
is not passed, Carbon return's current date and time.
Get a Carbon instance for the current date and time.
- timezone (optional): A string representing the timezone. Defaults to
null
.
const carbon = Carbon.now();
const carbon = Carbon.now('UTC');
Get a Carbon instance for today.
- timezone (optional) - A string representing the timezone. Defaults to
null
.
A Carbon instance representing today's date.
const carbon = Carbon.today();
console.log(carbon); // 2024-03-14 01:00:00.000 UTC (+01:00)
const carbon = Carbon.today('UTC');
console.log(carbon); // 2024-03-14 00:00:00.000 UTC (+00:00)
Note: This example assumes the current date is 2024-03-24.
Get a Carbon instance for tomorrow.
- timezone (optional) - A string representing the timezone. Defaults to
null
.
A Carbon instance representing tomorrow's date.
const carbon = Carbon.tomorrow();
console.log(carbon); // 2024-03-15 00:00:00.000 UTC (+01:00)
const carbon = Carbon.tomorrow('UTC');
console.log(carbon); // 2024-03-15 00:00:00.000 UTC (+00:00)
Note: This example assumes the current date is 2024-03-24.
Get a Carbon instance for yesterday.
- timezone (optional) - A string representing the timezone. Defaults to
null
.
A Carbon instance representing yesterday's date.
const carbon = Carbon.yesterday();
console.log(carbon); // 2024-03-13 00:00:00.000 UTC (+01:00)
const carbon = Carbon.yesterday('UTC');
console.log(carbon); // 2024-03-13 00:00:00.000 UTC (+00:00)
Note: This example assumes the current date is 2024-03-24.
Parse the date.
- date (optional) - A string representing the date. Defaults to
null
. - timezone (optional) - A string representing the timezone. Defaults to
null
.
const carbon = Carbon.parse('2024-03-14');
console.log(carbon); // 2024-03-14 01:00:00.000 UTC (+01:00)
const carbon = Carbon.parse('2024-03-14', 'UTC');
console.log(carbon); // 2024-03-14 00:00:00.000 UTC (+00:00)
Effortlessly format dates and times according to your preferred style and locale with Carbon's flexible formatting options.
Returns the formatted date string.
- format - A string representing the date format.
const carbon = Carbon.parse('2024-03-14').format('Y-m-d H:i:s');
console.log(carbon); // 2024-03-14 01:00:00
The format
method accepts a string that can contain any combination of the following tokens:
Format character | Description | Example |
---|---|---|
d | Day of the month, 2 digits with leading zeros. | 01 to 31 |
D | A textual representation of a day, three letters. | Mon through Sun |
j | Day of the month without leading zeros. | 1 to 31 |
l | A full textual representation of the day of the week. | Sunday through Saturday |
N | ISO 8601 numeric representation of the day of the week. | 1 (for Monday) through 7 (for Sunday) |
S | English ordinal suffix for the day of the month, 2 characters. | st, nd, rd or th |
w | Numeric representation of the day of the week. | 0 (for Sunday) through 6 (for Saturday) |
z | Numeric representation of the day of the week. | The day of the year (starting from 0) |
W | ISO 8601 week number of year, weeks starting on Monday. | 42 (the 42nd week in the year) |
F | A full textual representation of a month, such as January or March. | January through December |
m | Numeric representation of a month, with leading zeros. | 01 through 12 |
M | A short textual representation of a month, three letters. | Jan through Dec |
n | Numeric representation of a month, without leading zeros. | 1 through 12 |
t | Number of days in the given month. | 28 through 31 |
L | Whether it's a leap year. | 1 if it is a leap year, 0 otherwise |
o | ISO 8601 week-numbering year. This has the same value as Y, except that if the ISO week number (W) belongs to the previous or next year, that year is used instead. | 1999 or 2003 |
X | An expanded full numeric representation of a year, at least 4 digits, with for years BCE, and + for years CE. | -0055, +0787, +1999, +10191 |
x | An expanded full numeric representation if required, or a standard full numeral representation if possible (like Y). At least four digits. Years BCE are prefixed with a -. Years beyond (and including) 10000 are prefixed by a +. | -0055, 0787, 1999, +10191 |
Y | A full numeric representation of a year, at least 4 digits, with for years BCE. | -0055, 0787, 1999, 2003, 10191 |
y | A two-digit representation of a year. | 99 or 03 |
a | Lowercase Ante meridiem and Post meridiem. | am or pm |
A | Uppercase Ante meridiem and Post meridiem. | AM or PM |
B | Swatch Internet time. | 000 through 999 |
g | 12-hour format of an hour without leading zeros. | 1 through 12 |
G | 24-hour format of an hour without leading zeros. | 0 through 23 |
h | 12-hour format of an hour with leading zeros. | 01 through 12 |
H | 24-hour format of an hour with leading zeros. | 00 through 23 |
i | Minutes with leading zeros. | 00 to 59 |
s | Seconds with leading zeros. | 00 to 59 |
u | Microseconds. | 654321 |
v | Milliseconds. | 654 |
e | Timezone identifier. | UTC, GMT, Atlantic/Azores |
I | Whether or not the date is in daylight saving time. | 1 if Daylight Saving Time, 0 otherwise |
O | Difference to Greenwich time (GMT) without colon between hours and minutes. | +0200 |
P | Difference to Greenwich time (GMT) with colon between hours and minutes | +02:00 |
p | The same as P, but returns Z instead of +00:00. | +02:00 |
T | Timezone abbreviation, if known; otherwise the GMT offset. | EST, MDT, +05 |
Z | Timezone offset in seconds. The offset for timezones west of UTC is always negative, and for those east of UTC is always positive. | -43200 through 50400 |
c | ISO 8601 date. | 2004-02-12T15:19:21+00:00 |
r | Seconds since the Unix Epoch. | January 1 1970 00:00:00 GMT |
U | RFC 2822/RFC 5322 formatted date. | Thu, 21 Dec 2000 16:01:07 +0200 |
Microseconds (u
) are not supported due to JavaScript's Date object limitations.
Format the instance as date.
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toDateString();
console.log(carbon); // 2024-03-01
Format the instance as a formatted date.
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toFormattedDateString();
console.log(carbon); // Mar 1, 2024
Format the instance with the day and a formatted date.
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toFormattedDayDateString();
console.log(carbon); // Fri, Mar 1, 2024
Format the instance as time.
- precision (optional) - A string representing given unit precision. Defaults to
second
.
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toTimeString('millisecond');
console.log(carbon); // 12:45:00.000
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toTimeString('second');
console.log(carbon); // 12:45:00
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toTimeString('minute');
console.log(carbon); // 12:45
Format the instance as date and time.
- precision (optional) - A string representing given unit precision. Defaults to
second
.
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toDateTimeString('millisecond');
console.log(carbon); // 2024-03-01 12:45:00.000
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toDateTimeString('second');
console.log(carbon); // 2024-03-01 12:45:00
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toDateTimeString('minute');
console.log(carbon); // 2024-03-01 12:45
Format the instance as date and time T-separated with no timezone.
- precision (optional) - A string representing given unit precision. Defaults to
second
.
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toDateTimeLocalString('millisecond');
console.log(carbon); // 2024-03-01T12:45:00.000
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toDateTimeLocalString('second');
console.log(carbon); // 2024-03-01T12:45:00
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toDateTimeLocalString('minute');
console.log(carbon); // 2024-03-01T12:45
Format the instance with day, date and time.
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toDayDateTimeString();
console.log(carbon); // Fri, Mar 1, 2024 12:45 PM
Format the instance as ATOM.
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toAtomString();
console.log(carbon); // 2024-03-01T12:45:00+01:00
Format the instance as COOKIE.
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toCookieString();
console.log(carbon); // Friday, 01-Mar-2024 12:45:00 CET
Format the instance as ISO8601.
- keepOffset (optional) - Pass true to keep the date offset, else forced to UTC. Defaults to
false
.
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toIsoString();
console.log(carbon); // 2024-03-01T11:45:00.000Z
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toIsoString(true);
console.log(carbon); // 2024-03-01T12:45:00.000+01:00
Format the instance as ISO8601.
- extended (optional) - Determine whether to return extended format standard for Date and Time on the Internet.
Defaults to
false
.
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toIso8601String();
console.log(carbon); // 2024-03-01T12:45:00+0100
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toIso8601String(true);
console.log(carbon); // +2024-03-01T12:45:00+01:00
Convert the instance to UTC and return as Zulu ISO8601.
- precision (optional) - A string representing given unit precision. Defaults to
second
.
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toIso8601ZuluString('millisecond');
console.log(carbon); // 2024-03-01T11:45:00.000Z
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toIso8601ZuluString('second');
console.log(carbon); // 2024-03-01T11:45:00Z
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toIso8601ZuluString('minute');
console.log(carbon); // 2024-03-01T11:45Z
Format the instance as RFC822.
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toRfc822String();
console.log(carbon); // Fri, 01 Mar 24 12:45:00 +0100
Format the instance as RFC850.
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toRfc850String();
console.log(carbon); // Friday, 01-Mar-24 12:45:00 CET
Format the instance as RFC1036.
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toRfc1036String();
console.log(carbon); // Fri, 01 Mar 24 12:45:00 +0100
Format the instance as RFC1123.
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toRfc1123String();
console.log(carbon); // Fri, 01 Mar 2024 12:45:00 +0100
Format the instance as RFC2822.
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toRfc2822String();
console.log(carbon); // Fri, 01 Mar 2024 12:45:00 +0100
Format the instance as RFC3339.
- extended (optional) - Determine whether to return extended format standard for Date and Time on the Internet.
Defaults to
false
.
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toRfc3339String();
console.log(carbon); // 2024-03-01T12:45:00+01:00
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toRfc3339String(true);
console.log(carbon); // 2024-03-01T12:45:00.000+01:00
Format the instance as RFC7231.
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toRfc7231String();
console.log(carbon); // Fri, 01 Mar 2024 11:45:00 GMT
Format the instance as RSS.
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toRssString();
console.log(carbon); // Fri, 01 Mar 2024 12:45:00 +0100
Format the instance as W3C.
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toW3cString();
console.log(carbon); // 2024-03-01T12:45:00+01:00
Return a format from H:i to H:i:s.u according to given unit precision.
- precision (optional) - A string representing given unit precision. Defaults to
second
.
const carbon = Carbon.now().getTimeFormatByPrecision('millisecond');
console.log(carbon); // H:i:s.v
const carbon = Carbon.now().getTimeFormatByPrecision('second');
console.log(carbon); // H:i:s
const carbon = Carbon.now().getTimeFormatByPrecision('minute');
console.log(carbon); // H:i
Get default object representation.
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toObject();
console.log(carbon);
{
"year" : 2024,
"month" : 3,
"day" : 1,
"dayOfWeek": 5,
"dayOfYear": 61,
"hour" : 12,
"minute" : 45,
"second" : 0,
"micro" : undefined,
"timestamp": 1709293500,
"formatted": "2024-03-01 12:45:00",
"timezone" : "CET (+01:00)"
}
Return the ISO-8601 string with UTC timezone.
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toJson();
console.log(carbon); // 2024-03-01T11:45:00.000Z
Return native Date object matching the current instance.
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toDate();
console.log(carbon); // Date: "2024-03-01T11:45:00.000Z"
Format the instance as a string.
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toString();
console.log(carbon); // 2024-03-01 12:45:00.000 CET (+01:00)
Compare dates and times with precision and ease, utilizing Carbon's powerful comparison methods.
Determines if the instance's date and time are in the local timezone.
const carbon = Carbon.now().isLocal();
console.log(carbon); // true
const carbon = Carbon.now('UTC').isLocal();
console.log(carbon); // false
Note: In the provided example, the local timezone is Central European Standard Time (CET). Therefore, the example returns
true
, indicating that the Carbon instance's date and time are indeed in the local timezone.
Determines if the instance's date and time are in the UTC timezone.
const carbon = Carbon.now('UTC').isUtc();
console.log(carbon); // true
const carbon = Carbon.now().isUtc();
console.log(carbon); // false
Note: In the provided example, if the Carbon instance is created with the 'UTC' timezone, then
isUtc()
returnstrue
, indicating that the date and time are indeed in the UTC timezone. Conversely, if the instance is created without specifying 'UTC' (thus using the local timezone, which is Central European Standard Time (CET) in this case),isUtc()
returnsfalse
.
Determines if the instance's date and time is valid.
const carbon = Carbon.parse('2024-03-14');
console.log(carbon.isValid()); // true
const carbon = Carbon.parse('invalid date');
console.log(carbon.isValid()); // false
Determines if the instance's date and time is in daylight saving time.
const carbon = Carbon.parse('2024-07-14');
console.log(carbon.isDst()); // true
const carbon = Carbon.parse('2024-03-14');
console.log(carbon.isDst()); // false
Determines if the instance is a leap year.
const carbon = Carbon.parse('2024-03-14');
console.log(carbon.isLeapYear()); // true
const carbon = Carbon.parse('2023-03-14');
console.log(carbon.isLeapYear()); // false
Determines if the instance's day is Monday.
const carbon = Carbon.parse('2024-01-01');
console.log(carbon.isMonday()); // true
const carbon = Carbon.parse('2024-01-02');
console.log(carbon.isMonday()); // false
Determines if the instance's day is Tuesday.
const carbon = Carbon.parse('2024-01-02');
console.log(carbon.isTuesday()); // true
const carbon = Carbon.parse('2024-01-03');
console.log(carbon.isTuesday()); // false
Determines if the instance's day is Wednesday.
const carbon = Carbon.parse('2024-01-03');
console.log(carbon.isWednesday()); // true
const carbon = Carbon.parse('2024-01-04');
console.log(carbon.isWednesday()); // false
Determines if the instance's day is Thursday.
const carbon = Carbon.parse('2024-01-04');
console.log(carbon.isThursday()); // true
const carbon = Carbon.parse('2024-01-05');
console.log(carbon.isThursday()); // false
Determines if the instance's day is Friday.
const carbon = Carbon.parse('2024-01-05');
console.log(carbon.isFriday()); // true
const carbon = Carbon.parse('2024-01-06');
console.log(carbon.isFriday()); // false
Determines if the instance's day is Saturday.
const carbon = Carbon.parse('2024-01-06');
console.log(carbon.isSaturday()); // true
const carbon = Carbon.parse('2024-01-07');
console.log(carbon.isSaturday()); // false
Determines if the instance's day is Sunday.
const carbon = Carbon.parse('2024-01-07');
console.log(carbon.isSunday()); // true
const carbon = Carbon.parse('2024-01-08');
console.log(carbon.isSunday()); // false
Determines if the instance is a weekday.
const carbon = Carbon.parse('2024-03-14');
console.log(carbon.isWeekday()); // true
const carbon = Carbon.parse('2024-03-17');
console.log(carbon.isWeekday()); // false
Determines if the instance is a weekend day.
const carbon = Carbon.parse('2024-03-16');
console.log(carbon.isWeekend()); // true
const carbon = Carbon.parse('2024-03-14');
console.log(carbon.isWeekend()); // false
Determines if the instance is yesterday.
const carbon = Carbon.parse('2024-03-14');
console.log(carbon.isYesterday()); // true
const carbon = Carbon.parse('2024-03-15');
console.log(carbon.isYesterday()); // false
Note: These examples assume that "today" is 2024-03-15.
Determines if the instance is today.
const carbon = Carbon.parse('2024-03-15');
console.log(carbon.isToday()); // true
const carbon = Carbon.parse('2024-03-14');
console.log(carbon.isToday()); // false
Note: These examples assume that "today" is 2024-03-15.
Determines if the instance is tomorrow.
const carbon = Carbon.parse('2024-03-16');
console.log(carbon.isTomorrow()); // true
const carbon = Carbon.parse('2024-03-15');
console.log(carbon.isTomorrow()); // false
Note: These examples assume that "today" is 2024-03-15.
Determines if the instance is a specific day of the week.
- day - The day of the week as number or string. Property is case-insensitive when provided as a string.
const carbon = Carbon.parse('2024-03-14');
console.log(carbon.isDayOfWeek('thursday')); // true
const carbon = Carbon.parse('2024-03-14');
console.log(carbon.isDayOfWeek(2)); // false
Determines if the instance is the birthday, comparing only the month and day.
- date (optional) - The date to compare against, which can be a
Carbon
instance, a string date, ornull
. Defaults tonull
.
const carbon = Carbon.parse('2024-03-14');
const birthday = Carbon.parse('2000-03-14');
console.log(carbon.isBirthday(birthday)); // true
const carbon = Carbon.parse('2024-03-14');
const birthday = Carbon.parse('1995-04-22');
console.log(carbon.isBirthday(birthday)); // false
Determines if today is the last day of the month.
const carbon = Carbon.parse('2024-02-29');
console.log(carbon.isLastOfMonth()); // true
const carbon = Carbon.parse('2024-02-28');
console.log(carbon.isLastOfMonth()); // false
Determines if the instance is at the start of the day.
- checkMilliseconds (optional) - A boolean indicating whether to include milliseconds in the check. Defaults
to
false
.
const carbon = Carbon.parse('2024-03-14 00:00:00');
console.log(carbon.isStartOfDay()); // true
const carbon = Carbon.parse('2024-03-14 00:00:00.001');
console.log(carbon.isStartOfDay(true)); // false
Determines if the instance is at the end of the day.
- checkMilliseconds (optional) - A boolean indicating whether to include milliseconds in the check. Defaults
to
false
.
const carbon = Carbon.parse('2024-03-14 23:59:59');
console.log(carbon.isEndOfDay()); // true
const carbon = Carbon.parse('2024-03-14 23:59:59.999');
console.log(carbon.isEndOfDay(true)); // true
Determines if the instance is midnight.
const carbon = Carbon.parse('2024-03-14 00:00:00');
console.log(carbon.isMidnight()); // true
const carbon = Carbon.parse('2024-03-14 12:00:00');
console.log(carbon.isMidnight()); // false
Determines if the instance is midday.
const carbon = Carbon.parse('2024-03-14 12:00:00');
console.log(carbon.isMidday()); // true
const carbon = Carbon.parse('2024-03-14 11:59:59');
console.log(carbon.isMidday()); // false
Compares the formatted values of the two dates.
- format (required) - A string representing the format of the dates to be compared.
- date (optional) - An instance of
Carbon
, aDate
object, a string representing a date, ornull
. Defaults tonull
.
const carbon = Carbon.parse('2024-03-10 15:00:00', 'CET');
const date = '2024-03-10 15:00:00';
console.log(carbon.isSameAs('Y-m-d H:i:s', date)); // true
const carbon = Carbon.parse('2024-03-10 15:00:00', 'CET');
const date = Carbon.parse('2024-03-10 16:00:00', 'CET');
console.log(carbon.isSameAs('Y-m-d H:i:s', date)); // false
const carbon = Carbon.parse('2024-03-10', 'CET');
const date = Carbon.parse('2024-12-25', 'CET');
console.log(carbon.isSameAs('Y', date)); // true
const carbon = Carbon.parse('2024-03-10', 'CET');
const date = new Date('2024-03-10T00:00:00Z');
console.log(carbon.isSameAs('Y-m-d', date)); // true
const carbon = Carbon.parse('2024-03-10 15:00:00', 'CET');
const date = '2024-03-10';
console.log(carbon.isSameAs('Y-m-d H:i:s', date)); // false
console.log(carbon.isSameAs('Y-m-d', date)); // true
const today = new Carbon();
console.log(today.isSameAs('Y-m-d')); // true
Determine if the given date is in the same year as the instance. If null passed, compare to now (with the same timezone).
- date (optional) - An instance of
Carbon
, a string representing a date, ornull
. Defaults tonull
.
const carbon = Carbon.parse('2024-01-01', 'CET');
const date = Carbon.parse('2024-12-31', 'CET');
console.log(carbon.isSameYear(date)); // true
const carbon = Carbon.parse('2024-01-01', 'CET');
const date = Carbon.parse('2025-01-01', 'CET');
console.log(carbon.isSameYear(date)); // false
const date = new Date();
const carbon = Carbon.parse(date.toISOString(), 'CET');
console.log(carbon.isSameYear()); // true
const date = new Date();
date.setFullYear(date.getFullYear() + 1);
const carbon = Carbon.parse(date.toISOString(), 'CET');
console.log(carbon.isSameYear()); // false
Determine if the instance is in the same year as the current moment.
const date = new Date();
const carbon = Carbon.parse(date.toISOString(), 'CET');
console.log(carbon.isCurrentYear()); // true
const date = new Date();
date.setFullYear(date.getFullYear() + 1);
const carbon = Carbon.parse(date.toISOString(), 'CET');
console.log(carbon.isCurrentYear()); // false
Determine if the instance is in the same year as the current moment next year.
const nextYear = new Date();
nextYear.setFullYear(nextYear.getFullYear() + 1);
const carbon = Carbon.parse(nextYear.toISOString(), 'CET');
console.log(carbon.isNextYear()); // true
const date = new Date();
const carbon = Carbon.parse(date.toISOString(), 'CET');
console.log(carbon.isNextYear()); // false
Determine if the instance is in the same year as the current moment last year.
const lastYear = new Date();
lastYear.setFullYear(lastYear.getFullYear() - 1);
const carbon = Carbon.parse(lastYear.toISOString(), 'CET');
console.log(carbon.isLastYear()); // true
const date = new Date();
const carbon = Carbon.parse(date.toISOString(), 'CET');
console.log(carbon.isLastYear()); // false
Determine if the given date is in the same month as the instance. If null passed, compare to now (with the same timezone).
- date (optional) - An instance of
Carbon
, a string representing a date, ornull
. Defaults tonull
.
const carbon = Carbon.parse('2024-01-15', 'CET');
const date = Carbon.parse('2024-01-31', 'CET');
console.log(carbon.isSameMonth(date)); // true
const carbon = Carbon.parse('2024-01-01', 'CET');
const date = Carbon.parse('2024-02-01', 'CET');
console.log(carbon.isSameMonth(date)); // false
const date = new Date();
const carbon = Carbon.parse(date.toISOString(), 'CET');
console.log(carbon.isSameMonth()); // true
const date = new Date();
date.setMonth(date.getMonth() + 1);
const carbon = Carbon.parse(date.toISOString(), 'CET');
console.log(carbon.isSameMonth()); // false
Notice: The comparison is based on the format 'Y-m'.
Determine if the instance is in the same month as the current moment.
const date = new Date();
const carbon = Carbon.parse(date.toISOString(), 'CET');
console.log(carbon.isCurrentMonth()); // true
const date = new Date();
date.setMonth(date.getMonth() - 1);
const carbon = Carbon.parse(date.toISOString(), 'CET');
console.log(carbon.isCurrentMonth()); // false
Notice: The comparison is based on the format 'Y-m'.
Determine if the instance is in the same month as the current moment next month.
const nextMonth = new Date();
nextMonth.setMonth(nextMonth.getMonth() + 1);
const carbon = Carbon.parse(nextMonth.toISOString(), 'CET');
console.log(carbon.isNextMonth()); // true
const date = Carbon.now();
console.log(date.isNextMonth()); // false
Notice: The comparison is based on the format 'Y-m'.
Determine if the instance is in the same month as the current moment last month.
const lastMonth = new Date();
lastMonth.setMonth(lastMonth.getMonth() - 1);
const carbon = Carbon.parse(lastMonth.toISOString(), 'CET');
console.log(carbon.isLastMonth()); // true
const date = Carbon.now();
console.log(date.isLastMonth()); // false
Notice: The comparison is based on the format 'Y-m'.
Determine if the given date is in the same week as the instance. If null passed, compare to now (with the same timezone).
- date (optional) - An instance of
Carbon
, a string representing a date, ornull
. Defaults tonull
.
const startOfWeek = Carbon.parse('2024-03-04', 'CET');
const endOfWeek = Carbon.parse('2024-03-10', 'CET');
console.log(startOfWeek.isSameWeek(endOfWeek)); // true
const startOfWeek = Carbon.parse('2024-03-04', 'CET');
const nextWeek = Carbon.parse('2024-03-11', 'CET');
console.log(startOfWeek.isSameWeek(nextWeek)); // false
const date = new Date();
const carbon = Carbon.parse(date.toISOString(), 'CET');
console.log(carbon.isSameWeek()); // true
const nextWeek = new Date();
nextWeek.setDate(nextWeek.getDate() + 7);
const carbon = Carbon.parse(nextWeek.toISOString(), 'CET');
console.log(carbon.isSameWeek()); // false
Notice: The comparison is based on the format 'o-W'.
Determine if the instance is in the same week as the current moment.
const now = new Date();
const carbon = Carbon.parse(now.toISOString(), 'CET');
console.log(carbon.isCurrentWeek()); // true
const now = new Date();
now.setDate(now.getDate() + 7);
const carbon = Carbon.parse(now.toISOString(), 'CET');
console.log(carbon.isCurrentWeek()); // false
Notice: The comparison is based on the format 'o-W'.
Determine if the instance is in the same week as the current moment next week.
const now = new Date();
const nextWeek = new Date(now.getFullYear(), now.getMonth(), now.getDate() + 7);
const carbon = Carbon.parse(nextWeek.toISOString(), 'CET');
console.log(carbon.isNextWeek()); // true if in the same week as next week, false otherwise
const now = Carbon.now();
console.log(now.isNextWeek()); // false
Notice: The comparison is based on the format 'o-W'.
Determine if the instance is in the same week as the current moment last week.
const now = new Date();
const lastWeek = new Date(now.getFullYear(), now.getMonth(), now.getDate() - 7);
const carbon = Carbon.parse(lastWeek.toISOString(), 'CET');
console.log(carbon.isLastWeek()); // true
const now = Carbon.now();
console.log(now.isLastWeek()); // false
Notice: The comparison is based on the format 'o-W'.
Determine if the given date is in the same day as the instance. If null passed, compare to now (with the same timezone).
- date (optional) - An instance of
Carbon
, a string representing a date, ornull
. Defaults tonull
.
const date = new Date();
const carbon = Carbon.parse(date.toISOString(), 'CET');
console.log(carbon.isSameDay()); // true
const nextDay = new Date();
nextDay.setDate(nextDay.getDate() + 1);
const carbon = Carbon.parse(nextDay.toISOString(), 'CET');
console.log(carbon.isSameDay()); // false
Notice: The comparison is based on the format 'Y-m-d'.
Determine if the instance is in the same day as the current moment.
const now = new Date();
const carbon = Carbon.parse(now.toISOString(), 'CET');
console.log(carbon.isCurrentDay()); // true
const now = new Date();
now.setDate(now.getDate() + 1);
const carbon = Carbon.parse(now.toISOString(), 'CET');
console.log(carbon.isCurrentDay()); // false
Notice: The comparison is based on the format 'Y-m-d'.
Determine if the instance is in the same day as the current moment next day.
const now = new Date();
const nextDay = new Date(now.getFullYear(), now.getMonth(), now.getDate() + 1);
const carbon = Carbon.parse(nextDay.toISOString(), 'CET');
console.log(carbon.isNextDay()); // true if in the same day as next day, false otherwise
const now = Carbon.now();
console.log(now.isNextDay()); // false
Notice: The comparison is based on the format 'Y-m-d'.
Determine if the instance is in the same day as the current moment last day.
const now = new Date();
const lastDay = new Date(now.getFullYear(), now.getMonth(), now.getDate() - 1);
const carbon = Carbon.parse(lastDay.toISOString(), 'CET');
console.log(carbon.isLastDay()); // true
const now = Carbon.now();
console.log(now.isLastDay()); // false
Notice: The comparison is based on the format 'Y-m-d'.
Determine if the given date is in the same hour as the instance. If null passed, compare to now (with the same timezone).
- date (optional) - An instance of
Carbon
, a string representing a date, ornull
. Defaults tonull
.
const date = new Date();
const carbon = Carbon.parse(date.toISOString(), 'CET');
console.log(carbon.isSameHour()); // true
const nextHour = new Date();
nextHour.setHours(nextHour.getHours() + 1);
const carbon = Carbon.parse(nextHour.toISOString(), 'CET');
console.log(carbon.isSameHour()); // false
Notice: The comparison is based on the format 'Y-m-d H'.
Determine if the instance is in the same hour as the current moment.
const now = new Date();
const carbon = Carbon.parse(now.toISOString(), 'CET');
console.log(carbon.isCurrentHour()); // true
const now = new Date();
now.setHours(now.getHours() + 1);
const carbon = Carbon.parse(now.toISOString(), 'CET');
console.log(carbon.isCurrentHour()); // false
Notice: The comparison is based on the format 'Y-m-d H'.
Determine if the instance is in the same hour as the current moment next hour.
const now = new Date();
const nextHour = new Date(now.getFullYear(), now.getMonth(), now.getDate(), now.getHours() + 1);
const carbon = Carbon.parse(nextHour.toISOString(), 'CET');
console.log(carbon.isNextHour()); // true if in the same hour as next hour, false otherwise
const now = Carbon.now();
console.log(now.isNextHour()); // false
Notice: The comparison is based on the format 'Y-m-d H'.
Determine if the instance is in the same hour as the current moment last hour.
const now = new Date();
const lastHour = new Date(now.getFullYear(), now.getMonth(), now.getDate(), now.getHours() - 1);
const carbon = Carbon.parse(lastHour.toISOString(), 'CET');
console.log(carbon.isLastHour()); // true
const now = Carbon.now();
console.log(now.isLastHour()); // false
Notice: The comparison is based on the format 'Y-m-d H'.
Determine if the given date is in the same minute as the instance. If null passed, compare to now (with the same timezone).
- date (optional) - An instance of
Carbon
, a string representing a date, ornull
. Defaults tonull
.
const date = new Date();
const carbon = Carbon.parse(date.toISOString(), 'CET');
console.log(carbon.isSameMinute()); // true
const nextMinute = new Date();
nextMinute.setMinutes(nextMinute.getMinutes() + 1);
const carbon = Carbon.parse(nextMinute.toISOString(), 'CET');
console.log(carbon.isSameMinute()); // false
Notice: The comparison is based on the format 'Y-m-d H:i'.
Determine if the instance is in the same minute as the current moment.
const now = new Date();
const carbon = Carbon.parse(now.toISOString(), 'CET');
console.log(carbon.isCurrentMinute()); // true
const now = new Date();
now.setMinutes(now.getMinutes() + 1);
const carbon = Carbon.parse(now.toISOString(), 'CET');
console.log(carbon.isCurrentMinute()); // false
Notice: The comparison is based on the format 'Y-m-d H:i'.
Determine if the instance is in the same minute as the current moment next minute.
const now = new Date();
const nextMinute = new Date(now.getFullYear(), now.getMonth(), now.getDate(), now.getHours(), now.getMinutes() + 1);
const carbon = Carbon.parse(nextMinute.toISOString(), 'CET');
console.log(carbon.isNextMinute()); // true if in the same minute as next minute, false otherwise
const now = Carbon.now();
console.log(now.isNextMinute()); // false
Notice: The comparison is based on the format 'Y-m-d H:i'.
Determine if the instance is in the same minute as the current moment last minute.
const now = new Date();
const lastMinute = new Date(now.getFullYear(), now.getMonth(), now.getDate(), now.getHours(), now.getMinutes() - 1);
const carbon = Carbon.parse(lastMinute.toISOString(), 'CET');
console.log(carbon.isLastMinute()); // true
const now = Carbon.now();
console.log(now.isLastMinute()); // false
Notice: The comparison is based on the format 'Y-m-d H:i'.
Determine if the given date is in the same millisecond as the instance. If null passed, compare to now (with the same timezone).
- date (optional) - An instance of
Carbon
, a string representing a date, ornull
. Defaults tonull
.
const date = new Date();
const carbon = Carbon.parse(date.toISOString(), 'CET');
console.log(carbon.isSameMillisecond()); // true
const nextMillisecond = new Date();
nextMillisecond.setMilliseconds(nextMillisecond.getMilliseconds() + 1);
const carbon = Carbon.parse(nextMillisecond.toISOString(), 'CET');
console.log(carbon.isSameMillisecond()); // false
Notice: The comparison is based on the format 'Y-m-d H:i:s.v'.
Determine if the instance is in the same millisecond as the current moment.
const now = new Date();
const carbon = Carbon.parse(now.toISOString(), 'CET');
console.log(carbon.isCurrentMillisecond()); // true
const now = new Date();
now.setMilliseconds(now.getMilliseconds() + 1);
const carbon = Carbon.parse(now.toISOString(), 'CET');
console.log(carbon.isCurrentMillisecond()); // false
Notice: The comparison is based on the format 'Y-m-d H:i:s.v'.
Determine if the instance is in the same millisecond as the current moment next millisecond.
const now = new Date();
const nextMillisecond = new Date(now.getFullYear(), now.getMonth(), now.getDate(), now.getHours(), now.getMinutes(), now.getSeconds(), now.getMilliseconds() + 1);
const carbon = Carbon.parse(nextMillisecond.toISOString(), 'CET');
console.log(carbon.isNextMillisecond()); // true
const now = Carbon.now();
console.log(now.isNextMillisecond()); // false
Notice: The comparison is based on the format 'Y-m-d H:i:s.v'.
Determine if the instance is in the same millisecond as the current moment last millisecond.
const now = new Date();
const lastMillisecond = new Date(now.getFullYear(), now.getMonth(), now.getDate(), now.getHours(), now.getMinutes(), now.getSeconds(), now.getMilliseconds() - 1);
const carbon = Carbon.parse(lastMillisecond.toISOString(), 'CET');
console.log(carbon.isLastMillisecond()); // true
const now = Carbon.now();
console.log(now.isLastMillisecond()); // false
Notice: The comparison is based on the format 'Y-m-d H:i:s.v'.
Determine if the given date is in the same quarter as the instance. If null passed, compare to now (with the same timezone).
- date (optional) - An instance of
Carbon
, a string representing a date, ornull
. Defaults tonull
.
const date = new Date();
const carbon = Carbon.parse(date.toISOString(), 'CET');
console.log(carbon.isSameQuarter()); // true
const nextQuarter = new Date();
nextQuarter.setMonth(nextQuarter.getMonth() + 3);
const carbon = Carbon.parse(nextQuarter.toISOString(), 'CET');
console.log(carbon.isSameQuarter()); // false
Determine if the instance is in the same quarter as the current moment.
const now = new Date();
const carbon = Carbon.parse(now.toISOString(), 'CET');
console.log(carbon.isCurrentQuarter()); // true
const now = new Date();
now.setMonth(now.getMonth() + 3);
const carbon = Carbon.parse(now.toISOString(), 'CET');
console.log(carbon.isCurrentQuarter()); // false
Determine if the instance is in the same quarter as the current moment next quarter.
const now = new Date();
const nextQuarter = new Date(now.getFullYear(), now.getMonth() + 3, now.getDate());
const carbon = Carbon.parse(nextQuarter.toISOString(), 'CET');
console.log(carbon.isNextQuarter()); // true
const now = Carbon.now();
console.log(now.isNextQuarter()); // false
Determine if the instance is in the same quarter as the current moment last quarter.
const now = new Date();
const lastQuarter = new Date(now.getFullYear(), now.getMonth() - 3, now.getDate());
const carbon = Carbon.parse(lastQuarter.toISOString(), 'CET');
console.log(carbon.isLastQuarter()); // true
const now = Carbon.now();
console.log(now.isLastQuarter()); // false
Determine if the given date is in the same decade as the instance. If null passed, compare to now (with the same timezone).
- date (optional) - An instance of
Carbon
, a string representing a date, ornull
. Defaults tonull
.
const date = new Date();
const carbon = Carbon.parse(date.toISOString(), 'CET');
console.log(carbon.isSameDecade()); // true
const nextDecade = new Date();
nextDecade.setFullYear(nextDecade.getFullYear() + 10);
const carbon = Carbon.parse(nextDecade.toISOString(), 'CET');
console.log(carbon.isSameDecade()); // false
Determine if the instance is in the same decade as the current moment.
const now = new Date();
const carbon = Carbon.parse(now.toISOString(), 'CET');
console.log(carbon.isCurrentDecade()); // true
const now = new Date();
now.setFullYear(now.getFullYear() + 10);
const carbon = Carbon.parse(now.toISOString(), 'CET');
console.log(carbon.isCurrentDecade()); // false
Determine if the instance is in the same decade as the current moment next decade.
const now = new Date();
const nextDecade = new Date(now.getFullYear() + 10, now.getMonth(), now.getDate());
const carbon = Carbon.parse(nextDecade.toISOString(), 'CET');
console.log(carbon.isNextDecade()); // true
const now = Carbon.now();
console.log(now.isNextDecade()); // false
Determine if the instance is in the same decade as the current moment last decade.
const now = new Date();
const lastDecade = new Date(now.getFullYear() - 10, now.getMonth(), now.getDate());
const carbon = Carbon.parse(lastDecade.toISOString(), 'CET');
console.log(carbon.isLastDecade()); // true
const now = Carbon.now();
console.log(now.isLastDecade()); // false
Determine if the given date is in the same century as the instance. If null passed, compare to now (with the same timezone).
- date (optional) - An instance of
Carbon
, a string representing a date, ornull
. Defaults tonull
.
const date = new Date();
const carbon = Carbon.parse(date.toISOString(), 'CET');
console.log(carbon.isSameCentury()); // true
const nextCentury = new Date();
nextCentury.setFullYear(nextCentury.getFullYear() + 100);
const carbon = Carbon.parse(nextCentury.toISOString(), 'CET');
console.log(carbon.isSameCentury()); // false
Determine if the instance is in the same century as the current moment.
const now = new Date();
const carbon = Carbon.parse(now.toISOString(), 'CET');
console.log(carbon.isCurrentCentury()); // true
const now = new Date();
now.setFullYear(now.getFullYear() + 100);
const carbon = Carbon.parse(now.toISOString(), 'CET');
console.log(carbon.isCurrentCentury()); // false
Determine if the instance is in the same century as the current moment next century.
const now = new Date();
const nextCentury = new Date(now.getFullYear() + 100, now.getMonth(), now.getDate());
const carbon = Carbon.parse(nextCentury.toISOString(), 'CET');
console.log(carbon.isNextCentury()); // true
const now = Carbon.now();
console.log(now.isNextCentury()); // false
Determine if the instance is in the same century as the current moment last century.
const now = new Date();
const lastCentury = new Date(now.getFullYear() - 100, now.getMonth(), now.getDate());
const carbon = Carbon.parse(lastCentury.toISOString(), 'CET');
console.log(carbon.isLastCentury()); // true
const now = Carbon.now();
console.log(now.isLastCentury()); // false
Determine if the given date is in the same millennium as the instance. If null passed, compare to now (with the same timezone).
- date (optional) - An instance of
Carbon
, a string representing a date, ornull
. Defaults tonull
.
const date = new Date();
const carbon = Carbon.parse(date.toISOString(), 'CET');
console.log(carbon.isSameMillennium()); // true
const nextMillennium = new Date();
nextMillennium.setFullYear(nextMillennium.getFullYear() + 1000);
const carbon = Carbon.parse(nextMillennium.toISOString(), 'CET');
console.log(carbon.isSameMillennium()); // false
Determine if the instance is in the same millennium as the current moment.
const now = new Date();
const carbon = Carbon.parse(now.toISOString(), 'CET');
console.log(carbon.isCurrentMillennium()); // true
const now = new Date();
now.setFullYear(now.getFullYear() + 1000);
const carbon = Carbon.parse(now.toISOString(), 'CET');
console.log(carbon.isCurrentMillennium()); // false
Determine if the instance is in the same millennium as the current moment next millennium.
const now = new Date();
const nextMillennium = new Date(now.getFullYear() + 1000, now.getMonth(), now.getDate());
const carbon = Carbon.parse(nextMillennium.toISOString(), 'CET');
console.log(carbon.isNextMillennium()); // true
const now = Carbon.now();
console.log(now.isNextMillennium()); // false
Determine if the instance is in the same millennium as the current moment last millennium.
const now = new Date();
const lastMillennium = new Date(now.getFullYear() - 1000, now.getMonth(), now.getDate());
const carbon = Carbon.parse(lastMillennium.toISOString(), 'CET');
console.log(carbon.isLastMillennium()); // true
const now = Carbon.now();
console.log(now.isLastMillennium()); // false
Retrieve specific components of a date or time, such as year, month, day, hour, minute, and second, effortlessly with Carbon's getter functions.
Retrieve specific parts of the Carbon object using various keys.
Get the year.
const carbon = Carbon.parse('2024-03-16').get('year');
console.log(carbon); // 2024
Get the month number (1-12).
const carbon = Carbon.parse('2024-03-16').get('month');
console.log(carbon); // 3
Get the week number of the year.
const carbon = Carbon.parse('2024-03-16').get('week');
console.log(carbon); // 11
Get the day of the month.
const carbon = Carbon.parse('2024-03-16').get('day');
console.log(carbon); // 16
Get the hour of the day (0-23).
const carbon = Carbon.parse('2024-03-16 15:00').get('hour');
console.log(carbon); // 15
Get the minute.
const carbon = Carbon.parse('2024-03-16 15:30').get('minute');
console.log(carbon); // 30
Get the second.
const carbon = Carbon.parse('2024-03-16 15:30:45').get('second');
console.log(carbon); // 45
Get the millisecond.
const carbon = Carbon.parse('2024-03-16 12:00:00.123').get('millisecond');
console.log(carbon); // 123
Get the Unix timestamp.
const carbon = Carbon.parse('2024-03-16 12:00:00').get('timestamp');
console.log(carbon); // 1710586800
Get the day of the week (0 for Sunday, 6 for Saturday).
const carbon = Carbon.parse('2024-03-16').get('dayOfWeek');
console.log(carbon); // 6
Get the day of the year (1-365/366).
const carbon = Carbon.parse('2024-03-16').get('dayOfYear');
console.log(carbon); // 76
Get the number of days in the given month.
const carbon = Carbon.parse('2024-02').get('daysInMonth');
console.log(carbon); // 29
Get the quarter of the year (1-4).
const carbon = Carbon.parse('2024-03-16').get('quarter');
console.log(carbon); // 1
Get the decade.
const carbon = Carbon.parse('2024-03-16').get('decade');
console.log(carbon); // 203
Get the century.
const carbon = Carbon.parse('2024-03-16').get('century');
console.log(carbon); // 21
Get the millennium.
const carbon = Carbon.parse('2024-03-16').get('millennium');
console.log(carbon); // 3
Get the timezone offset in seconds from UTC.
const carbon = Carbon.parse('2024-03-16', 'CET').get('offset');
console.log(carbon); // 3600
Check if daylight saving time is in effect.
const carbon = Carbon.parse('2024-07-14').get('dst');
console.log(carbon); // true
const carbon = Carbon.parse('2024-03-14').get('dst');
console.log(carbon); // false
Check if the date is in local time.
const carbon = Carbon.now().get('local');
console.log(carbon); // true
const carbon = Carbon.now('UTC').get('local');
console.log(carbon); // false
Note: In the provided example, the local timezone is Central European Standard Time (CET). Therefore, the example returns
true
, indicating that the Carbon instance's date and time are indeed in the local timezone.
Check if the date is in UTC time.
const carbon = Carbon.parse('2024-03-16', 'UTC').get('utc');
console.log(carbon); // true
const carbon = Carbon.parse('2024-03-16', 'CET').get('utc');
console.log(carbon); // false
Get the timezone identifier.
const carbon = Carbon.parse('2024-03-16', 'CET').get('timezone');
console.log(carbon); // CET (+01:00)
Efficiently modify individual components of a date or time object using Carbon's convenient setter methods.
Set a specified unit of the Carbon
object to a new given value and return the updated Carbon
object.
- unit - A string representing the date. A string representing the unit to be
updated (
year
,month
,day
,hour
,minute
,second
, andmillisecond
). - value (optional) - The new value for the specified unit. Defaults to
null
(returns current value of the unit).
const carbon = Carbon.parse('2024-03-01 12:45:00').setUnit('year', 2025);
console.log(carbon); // 2025-03-01 12:45:00
const carbon = Carbon.parse('2024-03-01 12:45:00').setUnit('month', 8);
console.log(carbon); // 2024-08-01 12:45:00
const carbon = Carbon.parse('2024-03-01 12:45:00').setUnit('day', 15);
console.log(carbon); // 2024-03-15 12:45:00
const carbon = Carbon.parse('2024-03-01 12:45:00').setUnit('hour', 18);
console.log(carbon); // 2024-03-01 18:45:00
const carbon = Carbon.parse('2024-03-01 12:45:00').setUnit('minute', 30);
console.log(carbon); // 2024-03-01 12:30:00
const carbon = Carbon.parse('2024-03-01 12:45:00').setUnit('second', 59);
console.log(carbon); // 2024-03-01 12:45:59
const carbon = Carbon.parse('2024-03-01 12:45:00').setUnit('millisecond', 500);
console.log(carbon); // 2024-03-01 12:45:00.500
Set the current instance's year to the given value.
- value - The year to set the current
Carbon
instance to.
const carbon = Carbon.parse('2024-03-01 12:45:00').setYear(2025);
console.log(carbon); // 2025-03-01 12:45:00
Set the current instance's month to the given value.
- value - The month to set the current
Carbon
instance to.
const carbon = Carbon.parse('2024-03-01 12:45:00').setMonth(5);
console.log(carbon); // 2024-05-01 12:45:00
Set the current instance's day to the given value.
- value - The day to set the current
Carbon
instance to.
const carbon = Carbon.parse('2024-03-01 12:45:00').setDay(15);
console.log(carbon); // 2024-03-15 12:45:00
Set the current instance's hour to the given value.
- value - The hour to set the current
Carbon
instance to.
const carbon = Carbon.parse('2024-03-01 12:45:00').setHour(18);
console.log(carbon); // 2024-03-01 18:45:00
Set the current instance's minute to the given value.
- value - The minute to set the current
Carbon
instance to.
const carbon = Carbon.parse('2024-03-01 12:45:00').setMinute(30);
console.log(carbon); // 2024-03-01 12:30:00
Set the current instance's second to the given value.
- value - The second to set the current
Carbon
instance to.
const carbon = Carbon.parse('2024-03-01 12:45:00').setSecond(59);
console.log(carbon); // 2024-03-01 12:45:59
Set the current instance's millisecond to the given value.
- value - The millisecond to set the current
Carbon
instance to.
const carbon = Carbon.parse('2024-03-01 12:45:00').setMillisecond(500);
console.log(carbon); // 2024-03-01 12:45:00.500
Set the date with Gregorian year, month, and day numbers.
- year - The year in the Gregorian calendar.
- month - The month (0-11) in the Gregorian calendar.
- day - The day of the month (1-31) in the Gregorian calendar.
const carbon = Carbon.parse('2024-03-01 12:45:00').setDate(2025, 5, 15);
console.log(carbon); // 2025-06-15 12:45:00
Reset the current time of the Carbon
object to a different time.
- hour - The hour (0-23) of the new time.
- minute - The minute (0-59) of the new time.
- second - The second (0-59) of the new time.
- millisecond - The millisecond (0-999) of the new time.
const carbon = Carbon.parse('2024-03-01 12:45:00').setTime(18, 30, 45, 500);
console.log(carbon); // 2024-03-01 18:30:45.500
Set a specified unit to a new given value on the Carbon
object.
- unit - The date or time unit (
year
,month
,day
,hour
,minute
,second
,millisecond
) to update. - value - The new value for the specified unit. If
null
, no change is made to that unit.
const carbon = Carbon.parse('2024-03-01 12:45:00').setUnit('year', 2025);
console.log(carbon); // 2025-03-01 12:45:00
const carbon = Carbon.parse('2024-03-01 12:45:00').setUnit('month', 11);
console.log(carbon); // 2024-12-01 12:45:00
const carbon = Carbon.parse('2024-03-01 12:45:00').setUnit('day', 15);
console.log(carbon); // 2024-03-15 12:45:00
const carbon = Carbon.parse('2024-03-01 12:45:00').setUnit('hour', 18);
console.log(carbon); // 2024-03-01 18:45:00
const carbon = Carbon.parse('2024-03-01 12:45:00').setUnit('minute', 30);
console.log(carbon); // 2024-03-01 12:30:00
const carbon = Carbon.parse('2024-03-01 12:45:00').setUnit('second', 45);
console.log(carbon); // 2024-03-01 12:45:45
const carbon = Carbon.parse('2024-03-01 12:45:00').setUnit('millisecond', 500);
console.log(carbon); // 2024-03-01 12:45:00.500
Add the given units to the current Carbon
instance.
- unit - The unit to add (e.g., 'year', 'month', 'day', 'hour', etc.).
- value - The number of units to add. Default is 1.
A new Carbon
instance with the specified units added.
const carbon = Carbon.parse('2024-03-01 12:45:00').addUnit('year', 2);
console.log(carbon); // 2026-03-01 12:45:00
const carbon = Carbon.parse('2024-03-01 12:45:00').addUnit('month', 3);
console.log(carbon); // 2024-06-01 12:45:00
const carbon = Carbon.parse('2024-03-01 12:45:00').addUnit('day', 5);
console.log(carbon); // 2024-03-06 12:45:00
const carbon = Carbon.parse('2024-03-01 12:45:00').addUnit('hour', 10);
console.log(carbon); // 2024-03-02 22:45:00
const carbon = Carbon.parse('2024-03-01 12:45:00').addUnit('minute', 30);
console.log(carbon); // 2024-03-01 13:15:00
const carbon = Carbon.parse('2024-03-01 12:45:00').addUnit('second', 20);
console.log(carbon); // 2024-03-01 12:45:20
const carbon = Carbon.parse('2024-03-01 12:45:00').addUnit('millisecond', 500);
console.log(carbon); // 2024-03-01 12:45:00.500
const carbon = Carbon.parse('2024-03-01 12:45:00').addUnit('millennium', 1);
console.log(carbon); // 3024-03-01 12:45:00
const carbon = Carbon.parse('2024-03-01 12:45:00').addUnit('century', 1);
console.log(carbon); // 2124-03-01 12:45:00
const carbon = Carbon.parse('2024-03-01 12:45:00').addUnit('decade', 1);
console.log(carbon); // 2034-03-01 12:45:00
const carbon = Carbon.parse('2024-03-01 12:45:00').addUnit('quarter', 1);
console.log(carbon); // 2024-06-01 12:45:00
const carbon = Carbon.parse('2024-03-01 12:45:00').addUnit('week', 1);
console.log(carbon); // 2024-03-08 12:45:00
Add one year to the Carbon
instance.
const carbon = Carbon.parse('2024-03-01 12:45:00').addYear();
console.log(carbon); // 2025-03-01 12:45:00
Add years to the Carbon
instance.
- value - The number of years to add.
const carbon = Carbon.parse('2024-03-01 12:45:00').addYears(5);
console.log(carbon); // 2029-03-01 12:45:00
Add one month to the Carbon
instance.
const carbon = Carbon.parse('2024-03-01 12:45:00').addMonth();
console.log(carbon); // 2024-04-01 12:45:00
Add months to the Carbon
instance.
- value - The number of months to add.
const carbon = Carbon.parse('2024-03-01 12:45:00').addMonths(2);
console.log(carbon); // 2024-05-01 12:45:00
Add one day to the Carbon
instance.
const carbon = Carbon.parse('2024-03-01 12:45:00').addDay();
console.log(carbon); // 2024-03-02 12:45:00
Add days to the Carbon
instance.
- value - The number of days to add.
const carbon = Carbon.parse('2024-03-01 12:45:00').addDays(3);
console.log(carbon); // 2024-03-04 12:45:00
Add one hour to the Carbon
instance.
const carbon = Carbon.parse('2024-03-01 12:45:00').addHour();
console.log(carbon); // 2024-03-01 13:45:00
Add hours to the Carbon
instance.
- value - The number of hours to add.
const carbon = Carbon.parse('2024-03-01 12:45:00').addHours(2);
console.log(carbon); // 2024-03-01 14:45:00
Add one minute to the Carbon
instance.
const carbon = Carbon.parse('2024-03-01 12:45:00').addMinute();
console.log(carbon); // 2024-03-01 12:46:00
Add minutes to the Carbon
instance.
- value - The number of minutes to add.
const carbon = Carbon.parse('2024-03-01 12:45:00').addMinutes(30);
console.log(carbon); // 2024-03-01 13:15:00
Add one second to the Carbon
instance.
const carbon = Carbon.parse('2024-03-01 12:45:00').addSecond();
console.log(carbon); // 2024-03-01 12:45:01
Add seconds to the Carbon
instance.
- value - The number of seconds to add.
const carbon = Carbon.parse('2024-03-01 12:45:00').addSeconds(30);
console.log(carbon); // 2024-03-01 12:45:30
Add one millisecond to the Carbon
instance.
const carbon = Carbon.parse('2024-03-01 12:45:00').addMillisecond();
console.log(carbon); // 2024-03-01 12:45:00.001
Add milliseconds to the Carbon
instance.
- value - The number of milliseconds to add.
const carbon = Carbon.parse('2024-03-01 12:45:00').addMilliseconds(500);
console.log(carbon); // 2024-03-01 12:45:00.500
Add one millennium to the Carbon
instance.
const carbon = Carbon.parse('2024-03-01 12:45:00').addMillennium();
console.log(carbon); // 3024-03-01 12:45:00
Add millenniums to the Carbon
instance.
- value - The number of millenniums to add.
const carbon = Carbon.parse('2024-03-01 12:45:00').addMillenniums(2);
console.log(carbon); // 5024-03-01 12:45:00
Add one century to the Carbon
instance.
const carbon = Carbon.parse('2024-03-01 12:45:00').addCentury();
console.log(carbon); // 2124-03-01 12:45:00
Add centuries to the Carbon
instance.
- value - The number of centuries to add.
const carbon = Carbon.parse('2024-03-01 12:45:00').addCenturies(2);
console.log(carbon); // 2324-03-01 12:45:00
Add one decade to the Carbon
instance.
const carbon = Carbon.parse('2024-03-01 12:45:00').addDecade();
console.log(carbon); // 2034-03-01 12:45:00
Add decades to the Carbon
instance.
- value - The number of decades to add.
const carbon = Carbon.parse('2024-03-01 12:45:00').addDecades(2);
console.log(carbon); // 2044-03-01 12:45:00
Add one quarter to the Carbon
instance.
const carbon = Carbon.parse('2024-03-01 12:45:00').addQuarter();
console.log(carbon); // 2024-06-01 12:45:00
Add quarters to the Carbon
instance.
- value - The number of quarters to add.
const carbon = Carbon.parse('2024-03-01 12:45:00').addQuarters(2);
console.log(carbon); // 2024-09-01 12:45:00
Add one week to the Carbon
instance.
const carbon = Carbon.parse('2024-03-01 12:45:00').addWeek();
console.log(carbon); // 2024-03-08 12:45:00
Add weeks to the Carbon
instance.
- value - The number of weeks to add.
const carbon = Carbon.parse('2024-03-01 12:45:00').addWeeks(2);
console.log(carbon); // 2024-03-15 12:45:00
Subtract the given units from the current Carbon
instance.
- unit - The unit to subtract (e.g., 'year', 'month', 'day', 'hour', etc.).
- value - The number of units to subtract. Default is 1.
A new Carbon
instance with the specified units subtracted.
const carbon = Carbon.parse('2024-03-01 12:45:00').subUnit('year', 2);
console.log(carbon); // 2022-03-01 12:45:00
const carbon = Carbon.parse('2024-03-01 12:45:00').subUnit('month', 3);
console.log(carbon); // 2023-12-01 12:45:00
const carbon = Carbon.parse('2024-03-01 12:45:00').subUnit('day', 5);
console.log(carbon); // 2024-02-25 12:45:00
const carbon = Carbon.parse('2024-03-01 12:45:00').subUnit('hour', 10);
console.log(carbon); // 2024-02-29 02:45:00
const carbon = Carbon.parse('2024-03-01 12:45:00').subUnit('minute', 30);
console.log(carbon); // 2024-03-01 12:15:00
const carbon = Carbon.parse('2024-03-01 12:45:00').subUnit('second', 20);
console.log(carbon); // 2024-03-01 12:44:40
const carbon = Carbon.parse('2024-03-01 12:45:00').subUnit('millisecond', 500);
console.log(carbon); // 2024-03-01 12:44:59.500
const carbon = Carbon.parse('2024-03-01 12:45:00').subUnit('millennium', 1);
console.log(carbon); // 1024-03-01 12:45:00
const carbon = Carbon.parse('2024-03-01 12:45:00').subUnit('century', 1);
console.log(carbon); // 1924-03-01 12:45:00
const carbon = Carbon.parse('2024-03-01 12:45:00').subUnit('decade', 1);
console.log(carbon); // 2014-03-01 12:45:00
const carbon = Carbon.parse('2024-03-01 12:45:00').subUnit('quarter', 1);
console.log(carbon); // 2023-12-01 12:45:00
const carbon = Carbon.parse('2024-03-01 12:45:00').subUnit('week', 1);
console.log(carbon); // 2024-02-23 12:45:00
Subtract years from the Carbon
instance.
- value - The number of years to subtract.
const carbon = Carbon.parse('2024-03-01 12:45:00').subYears(2);
console.log(carbon); // 2022-03-01 12:45:00
Subtract one month from the Carbon
instance.
const carbon = Carbon.parse('2024-03-01 12:45:00').subMonth();
console.log(carbon); // 2024-02-01 12:45:00
Subtract months from the Carbon
instance.
- value - The number of months to subtract.
const carbon = Carbon.parse('2024-03-01 12:45:00').subMonths(2);
console.log(carbon); // 2024-01-01 12:45:00
Subtract one day from the Carbon
instance.
const carbon = Carbon.parse('2024-03-01 12:45:00').subDay();
console.log(carbon); // 2024-02-29 12:45:00
Subtract days from the Carbon
instance.
- value - The number of days to subtract.
const carbon = Carbon.parse('2024-03-01 12:45:00').subDays(2);
console.log(carbon); // 2024-02-28 12:45:00
Subtract one hour from the Carbon
instance.
const carbon = Carbon.parse('2024-03-01 12:45:00').subHour();
console.log(carbon); // 2024-03-01 11:45:00
Subtract hours from the Carbon
instance.
- value - The number of hours to subtract.
const carbon = Carbon.parse('2024-03-01 12:45:00').subHours(2);
console.log(carbon); // 2024-03-01 10:45:00
Subtract one minute from the Carbon
instance.
const carbon = Carbon.parse('2024-03-01 12:45:00').subMinute();
console.log(carbon); // 2024-03-01 12:44:00
Subtract minutes from the Carbon
instance.
- value - The number of minutes to subtract.
const carbon = Carbon.parse('2024-03-01 12:45:00').subMinutes(2);
console.log(carbon); // 2024-03-01 12:43:00
Subtract one second from the Carbon
instance.
const carbon = Carbon.parse('2024-03-01 12:45:00').subSecond();
console.log(carbon); // 2024-03-01 12:44:59
Subtract seconds from the Carbon
instance.
- value - The number of seconds to subtract.
const carbon = Carbon.parse('2024-03-01 12:45:00').subSeconds(2);
console.log(carbon); // 2024-03-01 12:44:58
Subtract one millisecond from the Carbon
instance.
const carbon = Carbon.parse('2024-03-01 12:45:00.123').subMillisecond();
console.log(carbon); // 2024-03-01 12:45:00.122
Subtract milliseconds from the Carbon
instance.
- value - The number of milliseconds to subtract.
const carbon = Carbon.parse('2024-03-01 12:45:00.123').subMilliseconds(30);
console.log(carbon); // 2024-03-01 12:45:00.093
Subtract one millennium (1000 years) from the Carbon
instance.
const carbon = Carbon.parse('3024-03-01 12:45:00').subMillennium();
console.log(carbon); // 2024-03-01 12:45:00
Subtract millenniums from the Carbon
instance.
- value - The number of millenniums to subtract.
const carbon = Carbon.parse('5024-03-01 12:45:00').subMillenniums(2);
console.log(carbon); // 3024-03-01 12:45:00
Subtract one century (100 years) from the Carbon
instance.
const carbon = Carbon.parse('2124-03-01 12:45:00').subCentury();
console.log(carbon); // 2024-03-01 12:45:00
Subtract centuries from the Carbon
instance.
- value - The number of centuries to subtract.
const carbon = Carbon.parse('2324-03-01 12:45:00').subCenturies(2);
console.log(carbon); // 2124-03-01 12:45:00
Subtract one decade (10 years) from the Carbon
instance.
const carbon = Carbon.parse('2034-03-01 12:45:00').subDecade();
console.log(carbon); // 2024-03-01 12:45:00
Subtract decades from the Carbon
instance.
- value - The number of decades to subtract.
const carbon = Carbon.parse('2054-03-01 12:45:00').subDecades(2);
console.log(carbon); // 2034-03-01 12:45:00
Subtract one quarter (3 months) from the Carbon
instance.
const carbon = Carbon.parse('2024-06-01 12:45:00').subQuarter();
console.log(carbon); // 2024-03-01 12:45:00
Subtract quarters from the Carbon
instance.
- value - The number of quarters to subtract.
const carbon = Carbon.parse('2025-03-01 12:45:00').subQuarters(4);
console.log(carbon); // 2024-03-01 12:45:00
Subtract one week (7 days) from the Carbon
instance.
const carbon = Carbon.parse('2024-03-08 12:45:00').subWeek();
console.log(carbon); // 2024-03-01 12:45:00
Subtract weeks from the Carbon
instance.
- value - The number of weeks to subtract.
const carbon = Carbon.parse('2024-03-29 12:45:00').subWeeks(4);
console.log(carbon); // 2024-03-01 12:45:00
You can chain multiple set
, add
or sub
methods together to conveniently update multiple components of a Carbon
instance in one
line.
const carbon = Carbon.parse('2024-03-01 12:45:00')
.setYear(2025)
.setMonth(5)
.setDay(15)
.setHour(18)
.setMinute(30)
.setSecond(45)
.setMillisecond(500);
console.log(carbon); // 2025-06-15 18:30:45.500 UTC (+02:00)
const carbon = Carbon.parse('2024-03-01 12:45:00')
.addYears(2)
.addMonths(3)
.addDays(5)
.addHours(10)
.addMinutes(30)
.addSeconds(20)
.addMilliseconds(500);
console.log(carbon); // 2026-06-06 23:15:20.500 UTC (+02:00)
const carbon = Carbon.parse('2024-03-01 12:45:00')
.subYears(2)
.subMonths(3)
.subDays(5)
.subHours(10)
.subMinutes(30)
.subSeconds(20)
.subMilliseconds(500);
console.log(carbon); // 2021-11-26 02:14:39.500 UTC (+01:00)
Calculate the precise difference between two dates or times using Carbon's robust methods.
Get the difference between the current Carbon
instance and another date as a DateInterval
instance.
- date - The date to compare with (e.g., another
Carbon
instance,Date
object, or date string). Default isnull
, which compares with the current date and time. - absolute - A boolean indicating whether the difference should be absolute. Default is
false
.
const carbon = Carbon.parse('2024-03-01 12:45:00');
const date = Carbon.parse('2022-03-01 12:45:00');
const diff = carbon.diff(date);
console.log(diff); // - 1y 11m 30d 23:59:59.999
const carbon = Carbon.parse('2024-03-01 12:45:00');
const date = Carbon.parse('2022-03-01 12:45:00');
const diff = carbon.diff(date, true);
console.log(diff); // + 1y 11m 30d 23:59:59.999
Get the difference in milliseconds between the current Carbon
instance and another date, rounded down.
- date - The date to compare with (e.g., another
Carbon
instance,Date
object, or date string). Default isnull
, which compares with the current date and time. - absolute - A boolean indicating whether the difference should be absolute. Default is
true
.
const carbon = Carbon.parse('2024-03-01 12:45:00');
const date = Carbon.parse('2022-03-01 12:45:00');
const diff = carbon.diffInMilliseconds(date);
console.log(diff); // 63158400000
const carbon = Carbon.parse('2024-03-01 12:45:00');
const date = Carbon.parse('2022-03-01 12:45:00');
const diff = carbon.diffInMilliseconds(date, false);
console.log(diff); // -63158400000
Get the difference in seconds between the current Carbon
instance and another date, rounded down.
- date - The date to compare with (e.g., another
Carbon
instance,Date
object, or date string). Default isnull
, which compares with the current date and time. - absolute - A boolean indicating whether the difference should be absolute. Default is
true
.
const carbon = Carbon.parse('2024-03-01 12:45:00');
const date = Carbon.parse('2022-03-01 12:45:00');
const diff = carbon.diffInSeconds(date);
console.log(diff); // 63158400
const carbon = Carbon.parse('2024-03-01 12:45:00');
const date = Carbon.parse('2022-03-01 12:45:00');
const diff = carbon.diffInSeconds(date, false);
console.log(diff); // -63158400
Get the difference in minutes between the current Carbon
instance and another date, rounded down.
- date - The date to compare with (e.g., another
Carbon
instance,Date
object, or date string). Default isnull
, which compares with the current date and time. - absolute - A boolean indicating whether the difference should be absolute. Default is
true
.
const carbon = Carbon.parse('2024-03-01 12:45:00');
const date = Carbon.parse('2022-03-01 12:45:00');
const diff = carbon.diffInMinutes(date);
console.log(diff); // 1052640
const carbon = Carbon.parse('2024-03-01 12:45:00');
const date = Carbon.parse('2022-03-01 12:45:00');
const diff = carbon.diffInMinutes(date, false);
console.log(diff); // -1052640
Get the difference in hours between the current Carbon
instance and another date, rounded down.
- date - The date to compare with (e.g., another
Carbon
instance,Date
object, or date string). Default isnull
, which compares with the current date and time. - absolute - A boolean indicating whether the difference should be absolute. Default is
true
.
const carbon = Carbon.parse('2024-03-01 12:45:00');
const date = Carbon.parse('2022-03-01 12:45:00');
const diff = carbon.diffInHours(date);
console.log(diff); // 17544
const carbon = Carbon.parse('2024-03-01 12:45:00');
const date = Carbon.parse('2022-03-01 12:45:00');
const diff = carbon.diffInHours(date, false);
console.log(diff); // -17544
Get the difference in days between the current Carbon
instance and another date, rounded down.
- date - The date to compare with (e.g., another
Carbon
instance,Date
object, or date string). Default isnull
, which compares with the current date and time. - absolute - A boolean indicating whether the difference should be absolute. Default is
true
.
const carbon = Carbon.parse('2024-03-01 12:45:00');
const date = Carbon.parse('2022-03-01 12:45:00');
const diff = carbon.diffInDays(date);
console.log(diff); // 731
const carbon = Carbon.parse('2024-03-01 12:45:00');
const date = Carbon.parse('2022-03-01 12:45:00');
const diff = carbon.diffInDays(date, false);
console.log(diff); // -731
Get the difference in weeks between the current Carbon
instance and another date, rounded down.
- date - The date to compare with (e.g., another
Carbon
instance,Date
object, or date string). Default isnull
, which compares with the current date and time. - absolute - A boolean indicating whether the difference should be absolute. Default is
true
.
const carbon = Carbon.parse('2024-03-01 12:45:00');
const date = Carbon.parse('2022-03-01 12:45:00');
const diff = carbon.diffInWeeks(date);
console.log(diff); // 104
const carbon = Carbon.parse('2024-03-01 12:45:00');
const date = Carbon.parse('2022-03-01 12:45:00');
const diff = carbon.diffInWeeks(date, false);
console.log(diff); // -104
Get the difference in months between the current Carbon
instance and another date, rounded down.
- date - The date to compare with (e.g., another
Carbon
instance,Date
object, or date string). Default isnull
, which compares with the current date and time. - absolute - A boolean indicating whether the difference should be absolute. Default is
true
.
const carbon = Carbon.parse('2024-03-01 12:45:00');
const date = Carbon.parse('2022-03-01 12:45:00');
const diff = carbon.diffInMonths(date);
console.log(diff); // 24
const carbon = Carbon.parse('2024-03-01 12:45:00');
const date = Carbon.parse('2022-03-01 12:45:00');
const diff = carbon.diffInMonths(date, false);
console.log(diff); // -24
Get the difference in quarters between the current Carbon
instance and another date, rounded down.
- date - The date to compare with (e.g., another
Carbon
instance,Date
object, or date string). Default isnull
, which compares with the current date and time. - absolute - A boolean indicating whether the difference should be absolute. Default is
true
.
const carbon = Carbon.parse('2024-03-01 12:45:00');
const date = Carbon.parse('2022-03-01 12:45:00');
const diff = carbon.diffInQuarters(date);
console.log(diff); // 8
const carbon = Carbon.parse('2024-03-01 12:45:00');
const date = Carbon.parse('2022-03-01 12:45:00');
const diff = carbon.diffInQuarters(date, false);
console.log(diff); // -8
Get the difference in years between the current Carbon
instance and another date.
- date - The date to compare with (e.g., another
Carbon
instance,Date
object, or date string). Default isnull
, which compares with the current date and time. - absolute - A boolean indicating whether the difference should be absolute. Default is
true
.
const carbon = Carbon.parse('2024-03-01 12:45:00');
const date = Carbon.parse('2022-03-01 12:45:00');
const diff = carbon.diffInYears(date);
console.log(diff); // 2
const carbon = Carbon.parse('2024-03-01 12:45:00');
const date = Carbon.parse('2022-03-01 12:45:00');
const diff = carbon.diffInYears(date, false);
console.log(diff); // -2