ISO_WEEK

The function ISO_WEEK takes a Date or a DateTime and returns a Number indicating the ISO week of the year that 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 ISO week of the year the given date falls on. Weeks start with Monday, and each week's year is the Gregorian year in which the Thursday falls.

Declaration

ISO_WEEK(datetime) -> iso_week_number

ISO_WEEK(date) -> iso_week_number

Parameters

datetime (type: DateTime) Any DateTime.

date (type: DateTime) Any Date.

Return Values

iso_week_number (type: Number) A number indicating what ISO week of the year is described by the given Date or DateTime. Count starts with 1. Weeks start with Monday, and each week's year is the Gregorian year in which the Thursday falls. That is, if the first day of the year falls on a Friday, Saturday, or a Sunday, it will count as being in the last week of the previous year, rather than the first week of the current year.

Examples

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. In 2021, the first day of the year falls on a Friday; as Friday comes after Thursday, January 1st, 2021 counts as part of the last week of 2020 instead of as part of the first week of 2021. This is reflected in the following example, where example_date_and_time is provided as input for the function ISO_WEEK:

ISO_WEEK(example_date_and_time) = 53

The above example demonstrates how the ISO_WEEK function behaves when given a DateTime as input. In order to further establish how the ISO_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 2021, and when example_date is given as input for ISO_WEEK, it again returns the number 53:

ISO_WEEK(example_date) = 53

January 1, 2021 falls on a Friday. This means that week 1 (as defined by the ISO_WEEK function) starts not on January 1, 2021, but on January 4, 2021, the first Monday in 2021 (in the week that contains the first Thursday of 2021). This is the date given by the following date, example_date2:

example_date2 = {  
 "day": 4,  
 "month": 1,  
 "year": 2021  
}

The following example outputs the ISO week of the year associated with January 4, 2021, The first ISO week of 2021:

ISO_WEEK(example_date2) = 1

While Monday, January 4, 2021 counts as part of the first week of 2021, the day before it, a Sunday, doesn't. To demonstrate this, assume the last example has access to the following date:

example_date3 = {  
 "day": 3,  
 "month": 1,  
 "year": 2021  
}

example_date3 describes Monday January 3, 2021, which is what the ISO_WEEK function 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 53, as in the following example:

ISO_WEEK(example_date3) = 53

Discussion

As far as the ISO_WEEK function is concerned, weeks start with Monday, and each week's year is the Gregorian year in which the Thursday falls. That is, if the first day of the year falls on a Friday, Saturday, or a Sunday, it will count as being in the last week of the previous year, rather than the first week of the current year. The examples discussed above demonstrated this by examining the first week in January 2021, for which the following calendar can serve as an individual aid:

Screen_Shot_2021-04-16_at_10.22.35_AM.png