Skip to content

Commit dd3b276

Browse files
author
Eric Koleda
committed
Adding code for the Date Add and Subtract add-on.
1 parent b39ebc0 commit dd3b276

File tree

2 files changed

+162
-0
lines changed

2 files changed

+162
-0
lines changed

‎date_add_and_subtract/Code.gs

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
// Copyright 2014 Google Inc. All Rights Reserved.
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
/**
16+
* @fileoverview Provides the custom functions DATEADD and DATESUBTRACT and
17+
* the helper functions that they use.
18+
*/
19+
20+
/*
21+
* Load the Moment library for date manipulation. Include it in your script
22+
* using the project key "MHMchiX6c1bwSqGM1PZiW_PxhMjh3Sh48".
23+
*/
24+
var moment = Moment.load();
25+
26+
/**
27+
* The list of valid unit identifiers.
28+
*/
29+
var VALID_UNITS = ['year', 'month', 'week', 'day', 'hour', 'minute', 'second',
30+
'millisecond'];
31+
32+
/**
33+
* The epoch date used by Google Sheets.
34+
*/
35+
var SHEETS_EPOCH = '12/30/1899 0:00:00';
36+
37+
/**
38+
* The number of seconds in a day.
39+
*/
40+
var SECONDS_PER_DAY = 86400;
41+
42+
/**
43+
* Runs when the add-on is installed.
44+
*/
45+
function onInstall() {
46+
onOpen();
47+
}
48+
49+
/**
50+
* Runs when the document is opened, creating the add-on's menu. Custom function
51+
* add-ons need at least one menu item, since the add-on is only enabled in the
52+
* current spreadsheet when a function is run.
53+
*/
54+
function onOpen() {
55+
SpreadsheetApp.getUi().createAddonMenu()
56+
.addItem('Use in this spreadsheet', 'use')
57+
.addToUi();
58+
}
59+
60+
/**
61+
* Enables the add-on on for the current spreadsheet (simply by running) and
62+
* shows a popup informing the user of the new functions that are available.
63+
*/
64+
function use() {
65+
var title = 'Date Custom Functions';
66+
var message = 'The functions DATEADD and DATESUBTRACT are now available in ' +
67+
'this spreadsheet. More information is available in the function help ' +
68+
'box that appears when you start using them in a forumula.';
69+
var ui = SpreadsheetApp.getUi();
70+
ui.alert(title, message, ui.ButtonSet.OK);
71+
}
72+
73+
/**
74+
* Adds some amount of time to a date.
75+
* @param {Date} date The date to add to.
76+
* @param {string} unit The unit of time to add. Possible values include:
77+
* `years`, `months`, `weeks`, `days`, `hours`, `minutes`, `seconds`, and
78+
* `milliseconds`. You can also use the shorthand notation for these units
79+
* which are `y`, `M`, `w`, `d`, `h`, `m`, `s`, `ms` respectively.
80+
* @param {number} amount The amount of the specified unit to add.
81+
* @return {Date} The new date.
82+
* @customFunction
83+
*/
84+
function DATEADD(date, unit, amount) {
85+
date = normalizeDate(date);
86+
validateParameters(date, unit, amount);
87+
return moment(date).add(unit, amount).toDate();
88+
}
89+
90+
/**
91+
* Subtracts some amount of time from a date.
92+
* @param {Date} date The date to subtract from.
93+
* @param {string} unit The unit of time to subtract. Possible values include:
94+
* `years`, `months`, `weeks`, `days`, `hours`, `minutes`, `seconds`, and
95+
* `milliseconds`. You can also use the shorthand notation for these units
96+
* which are `y`, `M`, `w`, `d`, `h`, `m`, `s`, `ms` respectively.
97+
* @param {number} amount The amount of the specified unit to subtract.
98+
* @return {Date} The new date.
99+
* @customFunction
100+
*/
101+
function DATESUBTRACT(date, unit, amount) {
102+
date = normalizeDate(date);
103+
validateParameters(date, unit, amount);
104+
return moment(date).subtract(unit, amount).toDate();
105+
}
106+
107+
/**
108+
* Normalizes a date value from Google Sheets, as they can sometimes be passed
109+
* as number values.
110+
* @param {?} date The date value.
111+
* @return {Date} The normalized date value.
112+
*/
113+
function normalizeDate(date) {
114+
if (typeof date == 'number') {
115+
var days = Math.floor(date);
116+
var seconds = (date - days) * SECONDS_PER_DAY;
117+
date = moment(SHEETS_EPOCH).add(days, 'days')
118+
.add(seconds, 'seconds').toDate();
119+
}
120+
return date;
121+
}
122+
123+
/**
124+
* Validates that the date, unit, and amount supplied are compatible with
125+
* Momnent, throwing an exception if any of the parameters are invalid.
126+
* @param {Date} date The date to add to or subtract from.
127+
* @param {string} unit The unit of time to add/subtract.
128+
* @param {number} amount The amount of the specified unit to add/subtract.
129+
*/
130+
function validateParameters(date, unit, amount) {
131+
if (date == undefined || typeof date == 'number' || !moment(date).isValid()) {
132+
throw Utilities.formatString('Parameter 1 expects a date value, but "%s" ' +
133+
'cannot be coerced to a date.', date);
134+
}
135+
if (VALID_UNITS.indexOf(moment.normalizeUnits(unit)) < 0) {
136+
throw Utilities.formatString('Parameter 2 expects a unit identifier, but ' +
137+
'"%s" is not a valid identifier.', unit);
138+
}
139+
if (isNaN(Number(amount))) {
140+
throw Utilities.formatString('Parameter 3 expects a number value, but ' +
141+
'"%s" cannot be coerced to a number.', amount);
142+
}
143+
}

‎date_add_and_subtract/README.md

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Date Add and Subtract
2+
3+
Date Add and Subtract is a sample
4+
[add-on for Google Sheets](https://developers.google.com/apps-script/add-ons)
5+
that provides custom functions for date manipulation. The script uses the
6+
[Moment.js](http://momentjs.com/) JavaScript library, which is packaged as an
7+
[Apps Script library](https://developers.google.com/apps-script/guide_libraries)
8+
and included with the key `MHMchiX6c1bwSqGM1PZiW_PxhMjh3Sh48`.
9+
10+
![Date Add and Subtract screenshot](https://googledrive.com/host/0BwzA1Orbvy5WV0tUQl9WX0FhRTA/date_add_and_subtract.png)
11+
12+
## Try it out
13+
14+
For your convience we have published the script to the Google Sheets
15+
[add-ons store](https://chrome.google.com/webstore/detail/date-add-and-subtract/mhdmhddjinipgjhpicaidhpimlmgnflb).
16+
Install the add-on via the store and follow the instructions to get started.
17+
18+
[![Analytics](https://ga-beacon.appspot.com/UA-42085206-1/google-apps-script-samples/date_add_and_subtract)](https://github.com/igrigorik/ga-beacon)
19+

0 commit comments

Comments
 (0)