Previous Page | Next Page

Functions and CALL Routines

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
Arguments
Details
The Basics
Aligning SAS Date Output within Its Intervals
SAME Alignment
Alignment Intervals
Adjusting Dates
Retail Calendar Intervals
Examples
Example 1: Examples of Using Intervals with the INTNX Function
Example 2: Example of Using Custom Intervals
See Also

Syntax

INTNX(interval<multiple><.shift-index>, start-from, increment<, 'alignment'>)
INTNX(custom-interval, start-from, increment <, 'alignment'>)


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.

Requirement: The type of interval (date, datetime, or time) must match the type of value in start-from and increment.
See: Commonly Used Time Intervals for a list of commonly used time intervals.

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>

Here are the three parts of the interval name:

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.

Restriction: 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.
Restriction: 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.

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

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

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.


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 the Intervals Used with Date and Time Functions table 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 the Intervals Used with Date and Time Functions table 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. Here is an 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)
intnx('year', '01mar1999'd, 1, 'same');   returns 29FEB2000 (the 60th day
                                          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.


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: ISP 8601 Compliant in SAS Language Reference: Concepts.


Examples


Example 1: Examples of Using Intervals with the INTNX Function

The following SAS statements produce these results.

SAS Statements Results
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 Statements Results
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

Functions:

INTCK Function

INTSHIFT Function

System Options:

INTERVALDS= System Option

Previous Page | Next Page | Top of Page