INTNX Function

Increments a date, time, or datetime value by a given time interval, and returns a date, time, or datetime value.

Category: Date and Time

Syntax

INTNX(custom-interval, start-from, increment <, 'alignment'> )

Required Arguments

interval

specifies a character constant, variable, or expression that contains a time interval such as WEEK, SEMIYEAR, QTR, or HOUR. Interval can appear in uppercase or lowercase. The possible values of interval are listed in the “Intervals Used with Date and Time Functions” table in SAS Language Reference: Concepts.

Tip
The type of interval (date, datetime, or time) must match the type of value in start-from.
Multipliers and shift indexes can be used with the basic interval names to construct more complex interval specifications. The general form of an interval name is as follows:

interval<multiple.shift-index>

The three parts of the interval name are listed below:

interval

specifies the name of the basic interval type. For example, YEAR specifies yearly intervals.

multiple

specifies an optional multiplier that sets the interval equal to a multiple of the period of the basic interval type. For example, the interval YEAR2 consists of two-year, or biennial, periods.

See Incrementing Dates and Times by Using Multipliers and by Shifting Intervals for more information.

shift-index

specifies an optional shift index that shifts the interval to start at a specified subperiod starting point. For example, YEAR.3 specifies yearly periods shifted to start on the first of March of each calendar year and to end in February of the following year.

Restrictions The shift index cannot be greater than the number of subperiods in the whole interval. For example, you could use YEAR2.24, but YEAR2.25 would be an error because there is no 25th month in a two-year interval.
If the default shift period is the same as the interval type, then only multiperiod intervals can be shifted with the optional shift index. For example, MONTH type intervals shift by MONTH subperiods by default. Thus, monthly intervals cannot be shifted with the shift index. However, bimonthly intervals can be shifted with the shift index because there are two MONTH intervals in each MONTH2 interval. The interval name MONTH2.2, for example, specifies bimonthly periods starting on the first day of even-numbered months.
See Incrementing Dates and Times by Using Multipliers and by Shifting Intervals for more information.

start-from

specifies a SAS expression that represents a SAS date, time, or datetime value that identifies a starting point.

increment

specifies a negative, positive, or zero integer that represents the number of date, time, or datetime intervals. Increment is the number of intervals to shift the value of start-from.

Optional Arguments

'alignment'

controls the position of SAS dates within the interval. You must enclose alignment in quotation marks. Alignment can be one of these values:

BEGINNING

specifies that the returned date or datetime value is aligned to the beginning of the interval.

Alias B

MIDDLE

specifies that the returned date or datetime value is aligned to the midpoint of the interval, which is the average of the beginning and ending alignment values.

Alias M

END

specifies that the returned date or datetime value is aligned to the end of the interval.

Alias E

SAME

specifies that the date that is returned has the same alignment as the input date.

Aliases S
SAMEDAY
See SAME Alignment for more information.
Default BEGINNING
See Aligning SAS Date Output within Its Intervals for more information.

custom-interval

specifies an interval that you define.

Details

The Basics

The INTNX function increments a date, time, or datetime value by intervals such as DAY, WEEK, QTR, and MINUTE, or a custom interval that you define. The increment is based on a starting date, time, or datetime value, and on the number of time intervals that you specify.
The INTNX function returns the SAS date value for the beginning date, time, or datetime value of the interval that you specify in the start–from argument. (To convert the SAS date value to a calendar date, use any valid SAS date format, such as the DATE9. format.) The following example shows how to determine the date of the start of the week that is six weeks from the week of October 17, 2003.
x=intnx('week', '17oct03'd, 6);
put x date9.;
INTNX returns the value 23NOV2003.
For more information about working with date and time intervals, see Date and Time Intervals.

Date and Datetime Intervals

The intervals that you need to use with SAS datetime values are SAS datetime intervals. Datetime intervals are formed by adding the prefix “DT” to any date interval. For example, MONTH is a SAS date interval, and DTMONTH is a SAS datetime interval. Similarly, YEAR is a SAS date interval, and DTYEAR is a SAS datetime interval.
To ensure correct results with interval functions, use date intervals with date values and datetime intervals with datetime values. SAS does not return an error message if you use a date value with a datetime interval, but the results are incorrect:
data _null_;
      /* The following statement creates expected results. */
   date1=intnx('dtday','01aug11:00:10:48'dt,1);
      /* The following two statements create unexpected results. */
   date2=intnx('dtday','01aug11'd,1);
   date3=intnx('dtday','01aug11:00:10:48'd,1);
   put 'Correct Datetime Value   ' date1= datetime19. /
       'Incorrect Datetime Value ' date2= datetime19. /
       'Incorrect Datetime Value ' date3= datetime19.;
run;
SAS writes the following output to the log:
Correct Datetime Value   date1=02AUG2011:00:00:00
Incorrect Datetime Value date2=02JAN1960:00:00:00
Incorrect Datetime Value date3=02JAN1960:00:00:00

Aligning SAS Date Output within Its Intervals

SAS date values are typically aligned with the beginning of the time interval that is specified with the interval argument.
You can use the optional alignment argument to specify the alignment of the date that is returned. The values BEGINNING, MIDDLE, or END align the date to the beginning, middle, or end of the interval, respectively.

SAME Alignment

If you use the SAME value of the alignment argument, then INTNX returns the same calendar date after computing the interval increment that you specified. The same calendar date is aligned based on the interval's shift period, not the interval. To view the valid shift periods, see Intervals Used with Date and Time Functions in SAS Language Reference: Concepts.
Most of the values of the shift period are equal to their corresponding intervals. The exceptions are the intervals WEEK, WEEKDAY, QTR, SEMIYEAR, YEAR, and their DT counterparts. WEEK and WEEKDAY intervals have a shift period of DAYS; and QTR, SEMIYEAR, and YEAR intervals have a shift period of MONTH. When you use SAME alignment with YEAR, for example, the result is same-day alignment based on MONTH, the interval's shift period. The result is not aligned to the same day of the YEAR interval. If you specify a multiple interval, then the default shift interval is based on the interval, and not on the multiple interval.
When you use SAME alignment for QTR, SEMIYEAR, and YEAR intervals, the computed date is the same number of months from the beginning of the interval as the input date. The day of the month matches as closely as possible. Because not all months have the same number of days, it is not always possible to match the day of the month.
For more information about shift periods, see Intervals Used with Date and Time Functions in SAS Language Reference: Concepts.

Alignment Intervals

Use the SAME value of the alignment argument if you want to base the alignment of the computed date on the alignment of the input date:
intnx('week', '15mar2000'd, 1, 'same');         returns 22MAR2000
intnx('dtweek', '15mar2000:8:45'dt, 1, 'same'); returns 22MAR00:08:45:00
intnx('year', '15mar2000'd, 5, 'same');        returns 15MAR2005

Adjusting Dates

The INTNX function automatically adjusts for the date if the date in the interval that is incremented does not exist. For example:
intnx('month', '15mar2000'd, 5, 'same');  returns 15AUG2000
intnx('year', '29feb2000'd, 2, 'same');   returns 28FEB2002
intnx('month', '31aug2001'd, 1, 'same');  returns 30SEP2001
intnx('year', '01mar1999'd, 1, 'same');   returns 01MAR2000 (the first day of the
                                                             third month of the year)
In the example intnx('year', '29feb2000'd, 2);, the INTNX function returns the value 01JAN2002, which is the beginning of the year two years from the starting date (2000).
In the example intnx('year', '29feb2000'd, 2, 'same');, the INTNX function returns the value 28FEB2002. In this case, the starting date begins in the year 2000, the year is two years later (2002), the month is the same (February), and the date is the 28th, because that is the closest date to the 29th in February 2002.

Custom Intervals

A custom interval is defined by a SAS data set. The data set must contain the begin variable, and it can also contain the end and season variables. Each observation represents one interval with the begin variable containing the start of the interval, and the end variable, if present, containing the end of the interval. The intervals must be listed in ascending order. You cannot have gaps between intervals, and intervals cannot overlap.
The SAS system option INTERVALDS= is used to define custom intervals and associate interval data sets with new interval names. The following example shows how to specify the INTERVALDS= system option:
options intervalds=(interval=libref.dataset-name);
Argument
interval
specifies the name of an interval. The value of interval is the data set that is named in libref.dataset-name.
libref.dataset-name
specifies the libref and data set name of the file that contains user-supplied holidays.
For more information, see Custom Time Intervals.

Retail Calendar Intervals

The retail industry often accounts for its data by dividing the yearly calendar into four 13-week periods, based on one of the following formats: 4-4-5, 4-5-4, or 5-4-4. The first, second, and third numbers specify the number of weeks in the first, second, and third month of each period, respectively. For more information, see Retail Calendar Intervals: ISO 8601 Compliant in SAS Language Reference: Concepts.

Examples

Example 1

The following SAS statements produce these results.
SAS Statement
Result
yr=intnx('year','05feb94'd,3);
put yr / yr date7.;
13515 
01JAN97
x=intnx('month','05jan95'd,0);
put x / x date7.;
12784
01JAN95
next=intnx('semiyear','01jan97'd,1);
put next / next date7.;
13696
01JUL97
past=intnx('month2','01aug96'd,-1);
put past / past date7.;
13270
01MAY96
sm=intnx('semimonth2.2','01apr97'd,4);
put sm / sm date7.;
13711 
16JUL97
x='month';
date='1jun1990'd;
nextmon=intnx(x,date,1);
put nextmon / nextmon date7.;
11139
01JUL90
x1='month     ';
x2=trim(x1);
date='1jun1990'd - 100;
nextmonth=intnx(x2,date,1);
put nextmonth / nextmonth date7.;
11017
01MAR90
The following examples show the results of advancing a date by using the optional alignment argument.
SAS Statement
Result
date1=intnx('month','01jan95'd,5,'beginning');
put date1 / date1 date7.;
 
12935 
01JUN95
date2=intnx('month','01jan95'd,5,'middle');
put date2 / date2 date7.;
 
12949
15JUN95
date3=intnx('month','01jan95'd,5,'end');
put date3 / date3 date7.;
 
12964
30JUN95
date4=intnx('month','01jan95'd,5,'sameday');
put date4 / date4 date7.;
 
12935
01JUN95
date5=intnx('month','15mar2000'd,5,'same');
put date5 / date5 date9.;
 
14837
15AUG2000
interval='month';
date='1sep2001'd;
align='m';
date4=intnx(interval,date,2,align);
put date4 / date4 date7.;
15294
15NOV01
x1='month     ';
x2=trim(x1);
date='1sep2001'd + 90;
date5=intnx(x2,date,2,'m');
put date5 / date5 date7.;
15356
16JAN02

Example 2: Example of Using Custom Intervals

The following example uses the custom-interval form of the INTNX function to increment a date, time, or datetime value by a given time interval.
options intervalds=(weekdaycust=dstest);
data dstest;
   format begin end date9.;
   begin='01jan2008'd; end='01jan2008'd; output;
   begin='02jan2008'd; end='02jan2008'd; output;
   begin='03jan2008'd; end='03jan2008'd; output;
   begin='04jan2008'd; end='06jan2008'd; output;
   begin='07jan2008'd; end='07jan2008'd; output;
   begin='08jan2008'd; end='08jan2008'd; output;
   begin='09jan2008'd; end='09jan2008'd; output;
   begin='10jan2008'd; end='10jan2008'd; output;
   begin='11jan2008'd; end='13jan2008'd; output;
   begin='14jan2008'd; end='14jan2008'd; output;
   begin='15jan2008'd; end='15jan2008'd; output;
run;
 
data _null_;
   format start date9. endcustom date9.;
   start='01jan2008'd;
   do i=0 to 9;
      endcustom=intnx('weekdaycust', start, i);
      put endcustom;
   end;
run;
SAS writes the following output to the log:
01JAN2008
02JAN2008
03JAN2008
04JAN2008
07JAN2008
08JAN2008
09JAN2008
10JAN2008
11JAN2008
14JAN2008

See Also

System Options:
INTERVALDS= System Option in SAS System Options: Reference