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 c