❤
npm
Sign UpSign In

@bjnstnkvc/carbon

1.0.3 • Public • Published

Carbon

JavaScript equivalent of Carbon date and time manipulation library.

Installation & setup

NPM

You can install the package via npm:

npm install @bjnstnkvc/carbon

and then import it into your project

import { Carbon } from '@bjnstnkvc/carbon';

CDN

You can install the package via jsDelivr CDN:

<script src="https://cdn.jsdelivr.net/npm/@bjnstnkvc/carbon/lib/main.min.js"></script>

Usage

Basic

Easily create, manipulate, and interact with date and time objects using Carbon's intuitive API.

Constructor

Create new Carbon instance.

Parameters
  • date (optional) - A string representing the date. Defaults to null.
  • timezone (optional) - A string representing the timezone. Defaults to null.
Example
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.

now

Get a Carbon instance for the current date and time.

Parameters
  • timezone (optional): A string representing the timezone. Defaults to null.
Example
const carbon = Carbon.now();
const carbon = Carbon.now('UTC');

today

Get a Carbon instance for today.

Parameters
  • timezone (optional) - A string representing the timezone. Defaults to null.
Returns

A Carbon instance representing today's date.

Example
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.

tomorrow

Get a Carbon instance for tomorrow.

Parameters
  • timezone (optional) - A string representing the timezone. Defaults to null.
Returns

A Carbon instance representing tomorrow's date.

Example
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.

yesterday

Get a Carbon instance for yesterday.

Parameters
  • timezone (optional) - A string representing the timezone. Defaults to null.
Returns

A Carbon instance representing yesterday's date.

Example
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

Parse the date.

Parameters
  • date (optional) - A string representing the date. Defaults to null.
  • timezone (optional) - A string representing the timezone. Defaults to null.
Example
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)

Formatting

Effortlessly format dates and times according to your preferred style and locale with Carbon's flexible formatting options.

format

Returns the formatted date string.

Parameters
  • format - A string representing the date format.
Example
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
Limitations

Microseconds (u) are not supported due to JavaScript's Date object limitations.

toDateString

Format the instance as date.

Example
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toDateString();

console.log(carbon); // 2024-03-01

toFormattedDateString

Format the instance as a formatted date.

Example
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toFormattedDateString();

console.log(carbon); // Mar 1, 2024

toFormattedDayDateString

Format the instance with the day and a formatted date.

Example
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toFormattedDayDateString();

console.log(carbon); // Fri, Mar 1, 2024

toTimeString

Format the instance as time.

Parameters
  • precision (optional) - A string representing given unit precision. Defaults to second.
Example
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

toDateTimeString

Format the instance as date and time.

Parameters
  • precision (optional) - A string representing given unit precision. Defaults to second.
Example
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

toDateTimeLocalString

Format the instance as date and time T-separated with no timezone.

Parameters
  • precision (optional) - A string representing given unit precision. Defaults to second.
Example
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

toDayDateTimeString

Format the instance with day, date and time.

Example
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toDayDateTimeString();

console.log(carbon); // Fri, Mar 1, 2024 12:45 PM

toAtomString

Format the instance as ATOM.

Example
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toAtomString();

console.log(carbon); // 2024-03-01T12:45:00+01:00

toCookieString

Format the instance as COOKIE.

Example
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toCookieString();

console.log(carbon); // Friday, 01-Mar-2024 12:45:00 CET

toIsoString

Format the instance as ISO8601.

Parameters
  • keepOffset (optional) - Pass true to keep the date offset, else forced to UTC. Defaults to false.
Example
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

toIso8601String

Format the instance as ISO8601.

Parameters
  • extended (optional) - Determine whether to return extended format standard for Date and Time on the Internet. Defaults to false.
Example
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

toIso8601ZuluString

Convert the instance to UTC and return as Zulu ISO8601.

Parameters
  • precision (optional) - A string representing given unit precision. Defaults to second.
Example
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

toRfc822String

Format the instance as RFC822.

Example
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toRfc822String();

console.log(carbon); // Fri, 01 Mar 24 12:45:00 +0100

toRfc850String

Format the instance as RFC850.

Example
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toRfc850String();

console.log(carbon); // Friday, 01-Mar-24 12:45:00 CET

toRfc1036String

Format the instance as RFC1036.

Example
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toRfc1036String();

console.log(carbon); // Fri, 01 Mar 24 12:45:00 +0100

toRfc1123String

Format the instance as RFC1123.

Example
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toRfc1123String();

console.log(carbon); // Fri, 01 Mar 2024 12:45:00 +0100

toRfc2822String

Format the instance as RFC2822.

Example
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toRfc2822String();

console.log(carbon); // Fri, 01 Mar 2024 12:45:00 +0100

toRfc3339String

Format the instance as RFC3339.

Parameters
  • extended (optional) - Determine whether to return extended format standard for Date and Time on the Internet. Defaults to false.
Example
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

toRfc7231String

Format the instance as RFC7231.

Example
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toRfc7231String();

console.log(carbon); // Fri, 01 Mar 2024 11:45:00 GMT

toRssString

Format the instance as RSS.

Example
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toRssString();

console.log(carbon); // Fri, 01 Mar 2024 12:45:00 +0100

toW3cString

Format the instance as W3C.

Example
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toW3cString();

console.log(carbon); // 2024-03-01T12:45:00+01:00

getTimeFormatByPrecision

Return a format from H:i to H:i:s.u according to given unit precision.

Parameters
  • precision (optional) - A string representing given unit precision. Defaults to second.
Example
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

toObject

Get default object representation.

Example
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)"
}

toJson

Return the ISO-8601 string with UTC timezone.

Example
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toJson();

console.log(carbon); // 2024-03-01T11:45:00.000Z

toDate

Return native Date object matching the current instance.

Example
const carbon = Carbon.parse('2024-03-01 12:45:00', 'CET').toDate();

console.log(carbon); // Date: "2024-03-01T11:45:00.000Z"

toString

Format the instance as a string.

Example
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)

Comparison

Compare dates and times with precision and ease, utilizing Carbon's powerful comparison methods.

isLocal

Determines if the instance's date and time are in the local timezone.

Examples
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.

isUtc

Determines if the instance's date and time are in the UTC timezone.

Examples
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() returns true, 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() returns false.

isValid

Determines if the instance's date and time is valid.

Examples
const carbon = Carbon.parse('2024-03-14');

console.log(carbon.isValid()); // true
const carbon = Carbon.parse('invalid date');

console.log(carbon.isValid()); // false

isDst

Determines if the instance's date and time is in daylight saving time.

Examples
const carbon = Carbon.parse('2024-07-14');

console.log(carbon.isDst()); // true
const carbon = Carbon.parse('2024-03-14');

console.log(carbon.isDst()); // false

isLeapYear

Determines if the instance is a leap year.

Examples
const carbon = Carbon.parse('2024-03-14');

console.log(carbon.isLeapYear()); // true
const carbon = Carbon.parse('2023-03-14');

console.log(carbon.isLeapYear()); // false

isMonday

Determines if the instance's day is Monday.

Examples
const carbon = Carbon.parse('2024-01-01');

console.log(carbon.isMonday()); // true
const carbon = Carbon.parse('2024-01-02');

console.log(carbon.isMonday()); // false

isTuesday

Determines if the instance's day is Tuesday.

Examples
const carbon = Carbon.parse('2024-01-02');

console.log(carbon.isTuesday()); // true
const carbon = Carbon.parse('2024-01-03');

console.log(carbon.isTuesday()); // false

isWednesday

Determines if the instance's day is Wednesday.

Examples
const carbon = Carbon.parse('2024-01-03');

console.log(carbon.isWednesday()); // true
const carbon = Carbon.parse('2024-01-04');

console.log(carbon.isWednesday()); // false

isThursday

Determines if the instance's day is Thursday.

Examples
const carbon = Carbon.parse('2024-01-04');

console.log(carbon.isThursday()); // true
const carbon = Carbon.parse('2024-01-05');

console.log(carbon.isThursday()); // false

isFriday

Determines if the instance's day is Friday.

Examples
const carbon = Carbon.parse('2024-01-05');

console.log(carbon.isFriday()); // true
const carbon = Carbon.parse('2024-01-06');

console.log(carbon.isFriday()); // false

isSaturday

Determines if the instance's day is Saturday.

Examples
const carbon = Carbon.parse('2024-01-06');

console.log(carbon.isSaturday()); // true
const carbon = Carbon.parse('2024-01-07');

console.log(carbon.isSaturday()); // false

isSunday

Determines if the instance's day is Sunday.

Examples
const carbon = Carbon.parse('2024-01-07');

console.log(carbon.isSunday()); // true
const carbon = Carbon.parse('2024-01-08');

console.log(carbon.isSunday()); // false

isWeekday

Determines if the instance is a weekday.

Examples
const carbon = Carbon.parse('2024-03-14');

console.log(carbon.isWeekday()); // true
const carbon = Carbon.parse('2024-03-17');

console.log(carbon.isWeekday()); // false

isWeekend

Determines if the instance is a weekend day.

Examples
const carbon = Carbon.parse('2024-03-16');

console.log(carbon.isWeekend()); // true
const carbon = Carbon.parse('2024-03-14');

console.log(carbon.isWeekend()); // false

isYesterday

Determines if the instance is yesterday.

Examples
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.

isToday

Determines if the instance is today.

Examples
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.

isTomorrow

Determines if the instance is tomorrow.

Examples
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.

isDayOfWeek

Determines if the instance is a specific day of the week.

Parameters
  • day - The day of the week as number or string. Property is case-insensitive when provided as a string.
Examples
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

isBirthday

Determines if the instance is the birthday, comparing only the month and day.

Parameters
  • date (optional) - The date to compare against, which can be a Carbon instance, a string date, or null. Defaults to null.
Examples
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

isLastOfMonth

Determines if today is the last day of the month.

Examples
const carbon = Carbon.parse('2024-02-29');

console.log(carbon.isLastOfMonth()); // true
const carbon = Carbon.parse('2024-02-28');

console.log(carbon.isLastOfMonth()); // false

isStartOfDay

Determines if the instance is at the start of the day.

Parameters
  • checkMilliseconds (optional) - A boolean indicating whether to include milliseconds in the check. Defaults to false.
Examples
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

isEndOfDay

Determines if the instance is at the end of the day.

Parameters
  • checkMilliseconds (optional) - A boolean indicating whether to include milliseconds in the check. Defaults to false.
Examples
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

isMidnight

Determines if the instance is midnight.

Examples
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

isMidday

Determines if the instance is midday.

Examples
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

isSameAs

Compares the formatted values of the two dates.

Parameters
  • format (required) - A string representing the format of the dates to be compared.
  • date (optional) - An instance of Carbon, a Date object, a string representing a date, or null. Defaults to null.
Example
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

isSameYear

Determine if the given date is in the same year as the instance. If null passed, compare to now (with the same timezone).

Parameters
  • date (optional) - An instance of Carbon, a string representing a date, or null. Defaults to null.
Example
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

isCurrentYear

Determine if the instance is in the same year as the current moment.

Example
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

isNextYear

Determine if the instance is in the same year as the current moment next year.

Example
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

isLastYear

Determine if the instance is in the same year as the current moment last year.

Example
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

isSameMonth

Determine if the given date is in the same month as the instance. If null passed, compare to now (with the same timezone).

Parameters
  • date (optional) - An instance of Carbon, a string representing a date, or null. Defaults to null.
Example
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'.

isCurrentMonth

Determine if the instance is in the same month as the current moment.

Example
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'.

isNextMonth

Determine if the instance is in the same month as the current moment next month.

Example
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'.

isLastMonth

Determine if the instance is in the same month as the current moment last month.

Example
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'.

isSameWeek

Determine if the given date is in the same week as the instance. If null passed, compare to now (with the same timezone).

Parameters
  • date (optional) - An instance of Carbon, a string representing a date, or null. Defaults to null.
Example
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'.

isCurrentWeek

Determine if the instance is in the same week as the current moment.

Example
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'.

isNextWeek

Determine if the instance is in the same week as the current moment next week.

Example
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'.

isLastWeek

Determine if the instance is in the same week as the current moment last week.

Example
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'.

isSameDay

Determine if the given date is in the same day as the instance. If null passed, compare to now (with the same timezone).

Parameters
  • date (optional) - An instance of Carbon, a string representing a date, or null. Defaults to null.
Example
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'.

isCurrentDay

Determine if the instance is in the same day as the current moment.

Example
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'.

isNextDay

Determine if the instance is in the same day as the current moment next day.

Example
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'.

isLastDay

Determine if the instance is in the same day as the current moment last day.

Example
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'.

isSameHour

Determine if the given date is in the same hour as the instance. If null passed, compare to now (with the same timezone).

Parameters
  • date (optional) - An instance of Carbon, a string representing a date, or null. Defaults to null.
Example
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'.

isCurrentHour

Determine if the instance is in the same hour as the current moment.

Example
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'.

isNextHour

Determine if the instance is in the same hour as the current moment next hour.

Example
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'.

isLastHour

Determine if the instance is in the same hour as the current moment last hour.

Example
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'.

isSameMinute

Determine if the given date is in the same minute as the instance. If null passed, compare to now (with the same timezone).

Parameters
  • date (optional) - An instance of Carbon, a string representing a date, or null. Defaults to null.
Example
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'.

isCurrentMinute

Determine if the instance is in the same minute as the current moment.

Example
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'.

isNextMinute

Determine if the instance is in the same minute as the current moment next minute.

Example
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'.

isLastMinute

Determine if the instance is in the same minute as the current moment last minute.

Example
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'.

isSameMillisecond

Determine if the given date is in the same millisecond as the instance. If null passed, compare to now (with the same timezone).

Parameters
  • date (optional) - An instance of Carbon, a string representing a date, or null. Defaults to null.
Example
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'.

isCurrentMillisecond

Determine if the instance is in the same millisecond as the current moment.

Example
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'.

isNextMillisecond

Determine if the instance is in the same millisecond as the current moment next millisecond.

Example
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'.

isLastMillisecond

Determine if the instance is in the same millisecond as the current moment last millisecond.

Example
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'.

isSameQuarter

Determine if the given date is in the same quarter as the instance. If null passed, compare to now (with the same timezone).

Parameters
  • date (optional) - An instance of Carbon, a string representing a date, or null. Defaults to null.
Example
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

isCurrentQuarter

Determine if the instance is in the same quarter as the current moment.

Example
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

isNextQuarter

Determine if the instance is in the same quarter as the current moment next quarter.

Example
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

isLastQuarter

Determine if the instance is in the same quarter as the current moment last quarter.

Example
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

isSameDecade

Determine if the given date is in the same decade as the instance. If null passed, compare to now (with the same timezone).

Parameters
  • date (optional) - An instance of Carbon, a string representing a date, or null. Defaults to null.
Example
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

isCurrentDecade

Determine if the instance is in the same decade as the current moment.

Example
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

isNextDecade

Determine if the instance is in the same decade as the current moment next decade.

Example
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

isLastDecade

Determine if the instance is in the same decade as the current moment last decade.

Example
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

isSameCentury

Determine if the given date is in the same century as the instance. If null passed, compare to now (with the same timezone).

Parameters
  • date (optional) - An instance of Carbon, a string representing a date, or null. Defaults to null.
Example
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

isCurrentCentury

Determine if the instance is in the same century as the current moment.

Example
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

isNextCentury

Determine if the instance is in the same century as the current moment next century.

Example
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

isLastCentury

Determine if the instance is in the same century as the current moment last century.

Example
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

isSameMillennium

Determine if the given date is in the same millennium as the instance. If null passed, compare to now (with the same timezone).

Parameters
  • date (optional) - An instance of Carbon, a string representing a date, or null. Defaults to null.
Example
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

isCurrentMillennium

Determine if the instance is in the same millennium as the current moment.

Example
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

isNextMillennium

Determine if the instance is in the same millennium as the current moment next millennium.

Example
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

isLastMillennium

Determine if the instance is in the same millennium as the current moment last millennium.

Example
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

Getters

Retrieve specific components of a date or time, such as year, month, day, hour, minute, and second, effortlessly with Carbon's getter functions.

get

Retrieve specific parts of the Carbon object using various keys.

Example
year

Get the year.

const carbon = Carbon.parse('2024-03-16').get('year');

console.log(carbon); // 2024
month

Get the month number (1-12).

const carbon = Carbon.parse('2024-03-16').get('month');

console.log(carbon); // 3
week

Get the week number of the year.

const carbon = Carbon.parse('2024-03-16').get('week');

console.log(carbon); // 11
day

Get the day of the month.

const carbon = Carbon.parse('2024-03-16').get('day');

console.log(carbon); // 16
hour

Get the hour of the day (0-23).

const carbon = Carbon.parse('2024-03-16 15:00').get('hour');

console.log(carbon); // 15
minute

Get the minute.

const carbon = Carbon.parse('2024-03-16 15:30').get('minute');

console.log(carbon); // 30
second

Get the second.

const carbon = Carbon.parse('2024-03-16 15:30:45').get('second');

console.log(carbon); // 45
millisecond

Get the millisecond.

const carbon = Carbon.parse('2024-03-16 12:00:00.123').get('millisecond');

console.log(carbon);  // 123
timestamp

Get the Unix timestamp.

const carbon = Carbon.parse('2024-03-16 12:00:00').get('timestamp');

console.log(carbon); // 1710586800
dayOfWeek

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
dayOfYear

Get the day of the year (1-365/366).

const carbon = Carbon.parse('2024-03-16').get('dayOfYear');

console.log(carbon); // 76
daysInMonth

Get the number of days in the given month.

const carbon = Carbon.parse('2024-02').get('daysInMonth');

console.log(carbon); // 29
quarter

Get the quarter of the year (1-4).

const carbon = Carbon.parse('2024-03-16').get('quarter');

console.log(carbon); // 1
decade

Get the decade.

const carbon = Carbon.parse('2024-03-16').get('decade');

console.log(carbon); // 203
century

Get the century.

const carbon = Carbon.parse('2024-03-16').get('century');

console.log(carbon); // 21
millennium

Get the millennium.

const carbon = Carbon.parse('2024-03-16').get('millennium');

console.log(carbon); // 3
offset

Get the timezone offset in seconds from UTC.

const carbon = Carbon.parse('2024-03-16', 'CET').get('offset');

console.log(carbon); // 3600
dst

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
local

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.

utc

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
timezone

Get the timezone identifier.

const carbon = Carbon.parse('2024-03-16', 'CET').get('timezone');

console.log(carbon); // CET (+01:00)

Setters

Efficiently modify individual components of a date or time object using Carbon's convenient setter methods.

setUnit

Set a specified unit of the Carbon object to a new given value and return the updated Carbon object.

Parameters
  • unit - A string representing the date. A string representing the unit to be updated (year, month, day, hour, minute, second, and millisecond).
  • value (optional) - The new value for the specified unit. Defaults to null (returns current value of the unit).
Example
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

setYear

Set the current instance's year to the given value.

Parameters
  • value - The year to set the current Carbon instance to.
Example
const carbon = Carbon.parse('2024-03-01 12:45:00').setYear(2025);

console.log(carbon); // 2025-03-01 12:45:00

setMonth

Set the current instance's month to the given value.

Parameters
  • value - The month to set the current Carbon instance to.
Example
const carbon = Carbon.parse('2024-03-01 12:45:00').setMonth(5);

console.log(carbon); // 2024-05-01 12:45:00

setDay

Set the current instance's day to the given value.

Parameters
  • value - The day to set the current Carbon instance to.
Example
const carbon = Carbon.parse('2024-03-01 12:45:00').setDay(15);

console.log(carbon); // 2024-03-15 12:45:00

setHour

Set the current instance's hour to the given value.

Parameters
  • value - The hour to set the current Carbon instance to.
Example
const carbon = Carbon.parse('2024-03-01 12:45:00').setHour(18);

console.log(carbon); // 2024-03-01 18:45:00

setMinute

Set the current instance's minute to the given value.

Parameters
  • value - The minute to set the current Carbon instance to.
Example
const carbon = Carbon.parse('2024-03-01 12:45:00').setMinute(30);

console.log(carbon); // 2024-03-01 12:30:00

setSecond

Set the current instance's second to the given value.

Parameters
  • value - The second to set the current Carbon instance to.
Example
const carbon = Carbon.parse('2024-03-01 12:45:00').setSecond(59);

console.log(carbon); // 2024-03-01 12:45:59

setMillisecond

Set the current instance's millisecond to the given value.

Parameters
  • value - The millisecond to set the current Carbon instance to.
Example
const carbon = Carbon.parse('2024-03-01 12:45:00').setMillisecond(500);

console.log(carbon); // 2024-03-01 12:45:00.500

setDate

Set the date with Gregorian year, month, and day numbers.

Parameters
  • 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.
Example
const carbon = Carbon.parse('2024-03-01 12:45:00').setDate(2025, 5, 15);

console.log(carbon); // 2025-06-15 12:45:00

setTime

Reset the current time of the Carbon object to a different time.

Parameters
  • 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.
Example
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

setUnit

Set a specified unit to a new given value on the Carbon object.

Parameters
  • 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.
Example
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

addUnit

Add the given units to the current Carbon instance.

Parameters
  • unit - The unit to add (e.g., 'year', 'month', 'day', 'hour', etc.).
  • value - The number of units to add. Default is 1.
Returns

A new Carbon instance with the specified units added.

Examples
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

addYear

Add one year to the Carbon instance.

Example
const carbon = Carbon.parse('2024-03-01 12:45:00').addYear();

console.log(carbon); // 2025-03-01 12:45:00

addYears

Add years to the Carbon instance.

Parameters
  • value - The number of years to add.
Example
const carbon = Carbon.parse('2024-03-01 12:45:00').addYears(5);

console.log(carbon); // 2029-03-01 12:45:00

addMonth

Add one month to the Carbon instance.

Example
const carbon = Carbon.parse('2024-03-01 12:45:00').addMonth();

console.log(carbon); // 2024-04-01 12:45:00

addMonths

Add months to the Carbon instance.

Parameters
  • value - The number of months to add.
Example
const carbon = Carbon.parse('2024-03-01 12:45:00').addMonths(2);

console.log(carbon); // 2024-05-01 12:45:00

addDay

Add one day to the Carbon instance.

Example
const carbon = Carbon.parse('2024-03-01 12:45:00').addDay();

console.log(carbon); // 2024-03-02 12:45:00

addDays

Add days to the Carbon instance.

Parameters
  • value - The number of days to add.
Example
const carbon = Carbon.parse('2024-03-01 12:45:00').addDays(3);

console.log(carbon); // 2024-03-04 12:45:00

addHour

Add one hour to the Carbon instance.

Example
const carbon = Carbon.parse('2024-03-01 12:45:00').addHour();

console.log(carbon); // 2024-03-01 13:45:00

addHours

Add hours to the Carbon instance.

Parameters
  • value - The number of hours to add.
Example
const carbon = Carbon.parse('2024-03-01 12:45:00').addHours(2);

console.log(carbon); // 2024-03-01 14:45:00

addMinute

Add one minute to the Carbon instance.

Example
const carbon = Carbon.parse('2024-03-01 12:45:00').addMinute();

console.log(carbon); // 2024-03-01 12:46:00

addMinutes

Add minutes to the Carbon instance.

Parameters
  • value - The number of minutes to add.
Example
const carbon = Carbon.parse('2024-03-01 12:45:00').addMinutes(30);

console.log(carbon); // 2024-03-01 13:15:00

addSecond

Add one second to the Carbon instance.

Example
const carbon = Carbon.parse('2024-03-01 12:45:00').addSecond();

console.log(carbon); // 2024-03-01 12:45:01

addSeconds

Add seconds to the Carbon instance.

Parameters
  • value - The number of seconds to add.
Example
const carbon = Carbon.parse('2024-03-01 12:45:00').addSeconds(30);

console.log(carbon); // 2024-03-01 12:45:30

addMillisecond

Add one millisecond to the Carbon instance.

Example
const carbon = Carbon.parse('2024-03-01 12:45:00').addMillisecond();

console.log(carbon); // 2024-03-01 12:45:00.001

addMilliseconds

Add milliseconds to the Carbon instance.

Parameters
  • value - The number of milliseconds to add.
Example
const carbon = Carbon.parse('2024-03-01 12:45:00').addMilliseconds(500);

console.log(carbon); // 2024-03-01 12:45:00.500

addMillennium

Add one millennium to the Carbon instance.

Example
const carbon = Carbon.parse('2024-03-01 12:45:00').addMillennium();

console.log(carbon); // 3024-03-01 12:45:00

addMillenniums

Add millenniums to the Carbon instance.

Parameters
  • value - The number of millenniums to add.
Example
const carbon = Carbon.parse('2024-03-01 12:45:00').addMillenniums(2);

console.log(carbon); // 5024-03-01 12:45:00

addCentury

Add one century to the Carbon instance.

Example
const carbon = Carbon.parse('2024-03-01 12:45:00').addCentury();

console.log(carbon); // 2124-03-01 12:45:00

addCenturies

Add centuries to the Carbon instance.

Parameters
  • value - The number of centuries to add.
Example
const carbon = Carbon.parse('2024-03-01 12:45:00').addCenturies(2);

console.log(carbon); // 2324-03-01 12:45:00

addDecade

Add one decade to the Carbon instance.

Example
const carbon = Carbon.parse('2024-03-01 12:45:00').addDecade();

console.log(carbon); // 2034-03-01 12:45:00

addDecades

Add decades to the Carbon instance.

Parameters
  • value - The number of decades to add.
Example
const carbon = Carbon.parse('2024-03-01 12:45:00').addDecades(2);

console.log(carbon); // 2044-03-01 12:45:00

addQuarter

Add one quarter to the Carbon instance.

Example
const carbon = Carbon.parse('2024-03-01 12:45:00').addQuarter();

console.log(carbon); // 2024-06-01 12:45:00

addQuarters

Add quarters to the Carbon instance.

Parameters
  • value - The number of quarters to add.
Example
const carbon = Carbon.parse('2024-03-01 12:45:00').addQuarters(2);

console.log(carbon); // 2024-09-01 12:45:00

addWeek

Add one week to the Carbon instance.

Example
const carbon = Carbon.parse('2024-03-01 12:45:00').addWeek();

console.log(carbon); // 2024-03-08 12:45:00

addWeeks

Add weeks to the Carbon instance.

Parameters
  • value - The number of weeks to add.
Example
const carbon = Carbon.parse('2024-03-01 12:45:00').addWeeks(2);

console.log(carbon); // 2024-03-15 12:45:00

subUnit

Subtract the given units from the current Carbon instance.

Parameters
  • unit - The unit to subtract (e.g., 'year', 'month', 'day', 'hour', etc.).
  • value - The number of units to subtract. Default is 1.
Returns

A new Carbon instance with the specified units subtracted.

Examples
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

subYears

Subtract years from the Carbon instance.

Parameters
  • value - The number of years to subtract.
Example
const carbon = Carbon.parse('2024-03-01 12:45:00').subYears(2);

console.log(carbon); // 2022-03-01 12:45:00

subMonth

Subtract one month from the Carbon instance.

Example
const carbon = Carbon.parse('2024-03-01 12:45:00').subMonth();

console.log(carbon); // 2024-02-01 12:45:00

subMonths

Subtract months from the Carbon instance.

Parameters
  • value - The number of months to subtract.
Example
const carbon = Carbon.parse('2024-03-01 12:45:00').subMonths(2);

console.log(carbon); // 2024-01-01 12:45:00

subDay

Subtract one day from the Carbon instance.

Example
const carbon = Carbon.parse('2024-03-01 12:45:00').subDay();

console.log(carbon); // 2024-02-29 12:45:00

subDays

Subtract days from the Carbon instance.

Parameters
  • value - The number of days to subtract.
Example
const carbon = Carbon.parse('2024-03-01 12:45:00').subDays(2);

console.log(carbon); // 2024-02-28 12:45:00

subHour

Subtract one hour from the Carbon instance.

Example
const carbon = Carbon.parse('2024-03-01 12:45:00').subHour();

console.log(carbon); // 2024-03-01 11:45:00

subHours

Subtract hours from the Carbon instance.

Parameters
  • value - The number of hours to subtract.
Example
const carbon = Carbon.parse('2024-03-01 12:45:00').subHours(2);

console.log(carbon); // 2024-03-01 10:45:00

subMinute

Subtract one minute from the Carbon instance.

Example
const carbon = Carbon.parse('2024-03-01 12:45:00').subMinute();

console.log(carbon); // 2024-03-01 12:44:00

subMinutes

Subtract minutes from the Carbon instance.

Parameters
  • value - The number of minutes to subtract.
Example
const carbon = Carbon.parse('2024-03-01 12:45:00').subMinutes(2);

console.log(carbon); // 2024-03-01 12:43:00

subSecond

Subtract one second from the Carbon instance.

Example
const carbon = Carbon.parse('2024-03-01 12:45:00').subSecond();

console.log(carbon); // 2024-03-01 12:44:59

subSeconds

Subtract seconds from the Carbon instance.

Parameters
  • value - The number of seconds to subtract.
Example
const carbon = Carbon.parse('2024-03-01 12:45:00').subSeconds(2);

console.log(carbon); // 2024-03-01 12:44:58

subMillisecond

Subtract one millisecond from the Carbon instance.

Example
const carbon = Carbon.parse('2024-03-01 12:45:00.123').subMillisecond();

console.log(carbon); // 2024-03-01 12:45:00.122

subMilliseconds

Subtract milliseconds from the Carbon instance.

Parameters
  • value - The number of milliseconds to subtract.
Example
const carbon = Carbon.parse('2024-03-01 12:45:00.123').subMilliseconds(30);

console.log(carbon); // 2024-03-01 12:45:00.093

subMillennium

Subtract one millennium (1000 years) from the Carbon instance.

Example
const carbon = Carbon.parse('3024-03-01 12:45:00').subMillennium();

console.log(carbon); // 2024-03-01 12:45:00

subMillenniums

Subtract millenniums from the Carbon instance.

Parameters
  • value - The number of millenniums to subtract.
Example
const carbon = Carbon.parse('5024-03-01 12:45:00').subMillenniums(2);

console.log(carbon); // 3024-03-01 12:45:00

subCentury

Subtract one century (100 years) from the Carbon instance.

Example
const carbon = Carbon.parse('2124-03-01 12:45:00').subCentury();

console.log(carbon); // 2024-03-01 12:45:00

subCenturies

Subtract centuries from the Carbon instance.

Parameters
  • value - The number of centuries to subtract.
Example
const carbon = Carbon.parse('2324-03-01 12:45:00').subCenturies(2);

console.log(carbon); // 2124-03-01 12:45:00

subDecade

Subtract one decade (10 years) from the Carbon instance.

Example
const carbon = Carbon.parse('2034-03-01 12:45:00').subDecade();

console.log(carbon); // 2024-03-01 12:45:00

subDecades

Subtract decades from the Carbon instance.

Parameters
  • value - The number of decades to subtract.
Example
const carbon = Carbon.parse('2054-03-01 12:45:00').subDecades(2);

console.log(carbon); // 2034-03-01 12:45:00

subQuarter

Subtract one quarter (3 months) from the Carbon instance.

Example
const carbon = Carbon.parse('2024-06-01 12:45:00').subQuarter();

console.log(carbon); // 2024-03-01 12:45:00

subQuarters

Subtract quarters from the Carbon instance.

Parameters
  • value - The number of quarters to subtract.
Example
const carbon = Carbon.parse('2025-03-01 12:45:00').subQuarters(4);

console.log(carbon); // 2024-03-01 12:45:00

subWeek

Subtract one week (7 days) from the Carbon instance.

Example
const carbon = Carbon.parse('2024-03-08 12:45:00').subWeek();

console.log(carbon); // 2024-03-01 12:45:00

subWeeks

Subtract weeks from the Carbon instance.

Parameters
  • value - The number of weeks to subtract.
Example
const carbon = Carbon.parse('2024-03-29 12:45:00').subWeeks(4);

console.log(carbon); // 2024-03-01 12:45:00

Chaining Method Calls

You can chain multiple set, add or sub methods together to conveniently update multiple components of a Carbon instance in one line.

Example
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)

Difference

Calculate the precise difference between two dates or times using Carbon's robust methods.

diff

Get the difference between the current Carbon instance and another date as a DateInterval instance.

Parameters
  • date - The date to compare with (e.g., another Carbon instance, Date object, or date string). Default is null, which compares with the current date and time.
  • absolute - A boolean indicating whether the difference should be absolute. Default is false.
Examples
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

diffInMilliseconds

Get the difference in milliseconds between the current Carbon instance and another date, rounded down.

Parameters
  • date - The date to compare with (e.g., another Carbon instance, Date object, or date string). Default is null, which compares with the current date and time.
  • absolute - A boolean indicating whether the difference should be absolute. Default is true.
Examples
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

diffInSeconds

Get the difference in seconds between the current Carbon instance and another date, rounded down.

Parameters
  • date - The date to compare with (e.g., another Carbon instance, Date object, or date string). Default is null, which compares with the current date and time.
  • absolute - A boolean indicating whether the difference should be absolute. Default is true.
Examples
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

diffInMinutes

Get the difference in minutes between the current Carbon instance and another date, rounded down.

Parameters
  • date - The date to compare with (e.g., another Carbon instance, Date object, or date string). Default is null, which compares with the current date and time.
  • absolute - A boolean indicating whether the difference should be absolute. Default is true.
Examples
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

diffInHours

Get the difference in hours between the current Carbon instance and another date, rounded down.

Parameters
  • date - The date to compare with (e.g., another Carbon instance, Date object, or date string). Default is null, which compares with the current date and time.
  • absolute - A boolean indicating whether the difference should be absolute. Default is true.
Examples
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

diffInDays

Get the difference in days between the current Carbon instance and another date, rounded down.

Parameters
  • date - The date to compare with (e.g., another Carbon instance, Date object, or date string). Default is null, which compares with the current date and time.
  • absolute - A boolean indicating whether the difference should be absolute. Default is true.
Examples
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

diffInWeeks

Get the difference in weeks between the current Carbon instance and another date, rounded down.

Parameters
  • date - The date to compare with (e.g., another Carbon instance, Date object, or date string). Default is null, which compares with the current date and time.
  • absolute - A boolean indicating whether the difference should be absolute. Default is true.
Examples
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

diffInMonths

Get the difference in months between the current Carbon instance and another date, rounded down.

Parameters
  • date - The date to compare with (e.g., another Carbon instance, Date object, or date string). Default is null, which compares with the current date and time.
  • absolute - A boolean indicating whether the difference should be absolute. Default is true.
Examples
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

diffInQuarters

Get the difference in quarters between the current Carbon instance and another date, rounded down.

Parameters
  • date - The date to compare with (e.g., another Carbon instance, Date object, or date string). Default is null, which compares with the current date and time.
  • absolute - A boolean indicating whether the difference should be absolute. Default is true.
Examples
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

diffInYears

Get the difference in years between the current Carbon instance and another date.

Parameters
  • date - The date to compare with (e.g., another Carbon instance, Date object, or date string). Default is null, which compares with the current date and time.
  • absolute - A boolean indicating whether the difference should be absolute. Default is true.
Examples
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

Readme

Keywords

Package Sidebar

Install

npm i @bjnstnkvc/carbon

Repository

github.com/BJNSTNKVC/js-carbon

Homepage

github.com/BJNSTNKVC/js-carbon#readme

Weekly Downloads

1

Version

1.0.3

License

MIT

Unpacked Size

486 kB

Total Files

11

Last publish

Collaborators

  • bjnstnkvc
Try on RunKit
Report malware