WEEK

The function WEEK takes a Date or a DateTime and returns a Number indicating what week of the year the given date falls on.

This function takes either a single DateTime or a single Date as input. It then a returns a Number indicating what week of the year the given date falls on. The precise definition of the a week depends on the location of the user.

Declaration

WEEK(datetime) -> week_number

WEEK(date) -> week_number

Parameters

datetime (type: DateTime)

Any DateTime.

date (type: Date)

Any Date.

Return Values

week_number (type: Number)

A number indicating what week of the year is described by the given Date or DateTime. Count starts with 1. The precise definition of a week depends on the location of the user, because different location define weeks differently. For example, in the United States, Sunday is the first day of the week. The week with January 1st in it is the first week of the year. In contrast, in France, Monday is the first day of the week, and the week with January 4th is the first week of the year.

Examples

The following examples assume that the user is in the United States, where weeks start with Sunday and the week with January 1st in it is the first week of the year. If calling on the WEEK function from another location, the results may differ subtly.

Assume the first example has access to the following DateTime value:

example_date_and_time = {  
 "date": {  
  "day": 1,  
  "month": 1,  
  "year": 2021  
 },  
 "time": {  
  "hour": 16,  
  "minute": 14,  
  "second": 38,  
  "millisecond": 0  
 },  
 "timeZone": "UTC"  
}

The date described in example_date_and_time is January 1st, 2021, the first day of the year, and thus within the first week of the year. This is reflected in the following example, where example_date_and_time is provided as input for the function WEEK:

WEEK(example_date_and_time) = 1

The above example demonstrates how the WEEK function behaves when given a DateTime as input. In order to further establish how the WEEK function behaves when given a Date rather than a DateTime, assume the next example has access to the following date value:

example_date = {  
 "day": 1,  
 "month": 1,  
 "year": 2021  
}

Note that the date described in example_date is identical to the date described in example_date_and_time. This is still the first day of the year, and when example_date is given as input for WEEK, it again returns the number 1:

WEEK(example_date) = 1

January 1, 2021 falls on a Friday. This means that week 1 (as defined by the United States) starts not on January 1, 2021, but on December 27, 2020, the last Sunday in 2020. This is the date given by the following date, example_date2:

example_date2 = {  
 "day": 27,  
 "month": 12,  
 "year": 2020  
}

The following example outputs the week of the year associated with December 27, 2020. Note that while this date is technically still in 2020, it is the last Sunday before the first day in 2021 (which is itself not a Sunday), and thus in the United States, the WEEK function counts it as being in the first week of 2021:

WEEK(example_date2) = 1

While Sunday December 27, 2020 counts as part of the first week of 2021 in the United States, the day before it, a Saturday, doesn't. To demonstrate this, assume the last example has access to the following date:

example_date3 = {  
 "day": 26,  
 "month": 12,  
 "year": 2020  
}

example_date3 describes Saturday December 26, 2020, which is what the United States considers the last day of the last week of 2020. Thus, when example_date3 is given as input for the WEEK function, it returns the number 52, as in the following example:

WEEK(example_date3) = 52

Discussion

The examples discussed above demonstrated the functionality of WEEK by examining the first week in January 2021, for which the following calendar can serve as an individual aid. Note that the calendar is arranged so that one full line of days marks one full week in the United States. Even when days are not visible, because they are in the previous or following months, they are still part of the same week as the visible days within their line: