/** Module: Utilities */ type Utilities = typeof Utilities; declare namespace Utilities { /** * Decodes a base-64 encoded string into a UTF-8 byte array. * *
* // This is the base64 encoded form of "Google グループ"
* var base64data = "R29vZ2xlIOOCsOODq+ODvOODlw==";
*
* // This logs:
* // [71, 111, 111, 103, 108, 101, 32, -29, -126, -80,
* // -29, -125, -85, -29, -125, -68, -29, -125, -105]
* var decoded = Utilities.base64Decode(base64data);
* Logger.log(decoded);
*
* // If we want a String instead of a byte array:
* // This logs the original "Google グループ"
* Logger.log(Utilities.newBlob(decoded).getDataAsString());
*
*
* @param encoded - an array of bytes of data to decode
*
* @returns the raw data represented by the base-64 encoded argument as a byte array
*/
function base64Decode(
encoded: string
): number[]
/**
* Decodes a base-64 encoded string into a byte array in a specific character set.
*
*
* // This is the base64 encoded form of "Google グループ"
* var base64data = "R29vZ2xlIOOCsOODq+ODvOODlw==";
*
* var decoded = Utilities.base64Decode(base64data, Utilities.Charset.UTF_8);
*
* // This logs:
* // [71, 111, 111, 103, 108, 101, 32, -29, -126, -80,
* // -29, -125, -85, -29, -125, -68, -29, -125, -105]
* Logger.log(decoded);
*
* // If we want a String instead of a byte array:
* // This logs the original "Google グループ"
* Logger.log(Utilities.newBlob(decoded).getDataAsString());
*
*
* @param encoded - the string of data to decode
* @param charset - a Charset specifying the charset of the input
*
* @returns the raw data represented by the base-64 encoded argument as a byte array
*/
function base64Decode(
encoded: string,
charset: Utilities.Charset
): number[]
/**
* Decodes a base-64 web-safe encoded string into a UTF-8 byte array.
*
*
* // This is the base64 web-safe encoded form of "Google グループ"
* var base64data = "R29vZ2xlIOOCsOODq-ODvOODlw==";
*
* var decoded = Utilities.base64DecodeWebSafe(base64data);
*
* // This logs:
* // [71, 111, 111, 103, 108, 101, 32, -29, -126, -80,
* // -29, -125, -85, -29, -125, -68, -29, -125, -105]
* Logger.log(decoded);
*
* // If we want a String instead of a byte array:
* // This logs the original "Google グループ"
* Logger.log(Utilities.newBlob(decoded).getDataAsString());
*
*
* @param encoded - an array of bytes of web-safe data to decode
*
* @returns the raw data represented by the base-64 web-safe encoded argument as a byte array
*/
function base64DecodeWebSafe(
encoded: string
): number[]
/**
* Decodes a base-64 web-safe encoded string into a byte array in a specific character set.
*
*
* // This is the base64 web-safe encoded form of "Google グループ"
* var base64data = "R29vZ2xlIOOCsOODq-ODvOODlw==";
*
* var decoded = Utilities.base64DecodeWebSafe(base64data, Utilities.Charset.UTF_8);
*
* // This logs:
* // [71, 111, 111, 103, 108, 101, 32, -29, -126, -80,
* // -29, -125, -85, -29, -125, -68, -29, -125, -105]
* Logger.log(decoded);
*
* // If we want a String instead of a byte array:
* // This logs the original "Google グループ"
* Logger.log(Utilities.newBlob(decoded).getDataAsString());
*
*
* @param encoded - the string of web-safe data to decode
* @param charset - a Charset specifying the charset of the input
*
* @returns the raw data represented by the base-64 web-safe encoded argument as a byte array
*/
function base64DecodeWebSafe(
encoded: string,
charset: Utilities.Charset
): number[]
/**
* Generates a base-64 encoded string from the given byte array. Base 64 is a common encoding
* accepted by a variety of tools that cannot accept binary data. Base 64 is commonly used in
* internet protocols such as email, HTTP, or in XML documents.
*
*
* // Instantiates a blob here for clarity
* var blob = Utilities.newBlob("A string here");
*
* // Writes 'QSBzdHJpbmcgaGVyZQ==' to the log.
* var encoded = Utilities.base64Encode(blob.getBytes());
* Logger.log(encoded);
*
*
* @param data - a byte[] of data to encode
*
* @returns the base-64 encoded representation of the passed in data
*/
function base64Encode(
data: number[]
): string
/**
* Generates a base-64 encoded string from the given string. Base 64 is a common encoding accepted
* by a variety of tools that cannot accept binary data. Base 64 is commonly used in internet
* protocols such as email, HTTP, or in XML documents.
*
*
* // Writes 'QSBzdHJpbmcgaGVyZQ==' to the log.
* var encoded = Utilities.base64Encode("A string here");
* Logger.log(encoded);
*
*
* @param data - the string to encode
*
* @returns the base-64 encoded representation of the input string
*/
function base64Encode(
data: string
): string
/**
* Generates a base-64 encoded string from the given string in a specific character set. A Charset
* is a way of encoding characters such that they can be encoded. These are typically done in a
* binary format, which can generally be incompatible with certain data transmission protocols. To
* make the data compatible, they are generally encoded into base 64, which is a common encoding
* accepted by a variety of tools that cannot accept binary data. Base 64 is commonly used in
* internet protocols such as email, HTTP, or in XML documents.
*
*
* // "Google Groups" in Katakana (Japanese)
* var input = "Google グループ";
*
* // Writes "R29vZ2xlIOOCsOODq+ODvOODlw==" to the log
* var encoded = Utilities.base64Encode(input, Utilities.Charset.UTF_8);
* Logger.log(encoded);
*
*
*
* @param data - the string of data to encode
* @param charset - a Charset specifying the charset of the input
*
* @returns the base-64 encoded representation of the input string with the given Charset
*/
function base64Encode(
data: string,
charset: Utilities.Charset
): string
/**
* Generates a base-64 web-safe encoded string from the given byte array. Base 64 is a common
* encoding accepted by a variety of tools that cannot accept binary data. Base 64 web-safe is
* commonly used in internet protocols such as email, HTTP, or in XML documents.
*
*
* // Instantiates a blob here for clarity
* var blob = Utilities.newBlob("A string here");
*
* // Writes 'QSBzdHJpbmcgaGVyZQ==' to the log.
* var encoded = Utilities.base64EncodeWebSafe(blob.getBytes());
* Logger.log(encoded);
*
*
* @param data - an array of bytes of data to encode
*
* @returns the base-64 web-safe encoded representation of the passed in data
*/
function base64EncodeWebSafe(
data: number[]
): string
/**
* Generates a base-64 web-safe encoded string from the given string. Base 64 is a common encoding
* accepted by a variety of tools that cannot accept binary data. Base 64 web-safe is commonly
* used in internet protocols such as email, HTTP, or in XML documents.
*
*
* // Writes 'QSBzdHJpbmcgaGVyZQ==' to the log.
* var encoded = Utilities.base64EncodeWebSafe("A string here");
* Logger.log(encoded);
*
*
* @param data - the string to encode
*
* @returns the base-64 web-safe encoded representation of the input string
*/
function base64EncodeWebSafe(
data: string
): string
/**
* Generates a base-64 web-safe encoded string from the given string in a specific character set.
* A Charset is a way of encoding characters such that they can be encoded. These are typically
* done in a binary format, which can generally be incompatible with certain data transmission
* protocols. To make the data compatible, they are generally encoded into base 64, which is a
* common encoding accepted by a variety of tools that cannot accept binary data. Base 64 web-safe
* is commonly used in internet protocols such as email, HTTP, or in XML documents.
*
*
* // "Google Groups" in Katakana (Japanese)
* var input = "Google グループ";
*
* // Writes "R29vZ2xlIOOCsOODq-ODvOODlw==" to the log
* var encoded = Utilities.base64EncodeWebSafe(input, Utilities.Charset.UTF_8);
* Logger.log(encoded);
*
*
*
* @param data - the string of data to encode
* @param charset - a Charset specifying the charset of the input
*
* @returns the base-64 web-safe encoded representation of the input string with the given Charset
*/
function base64EncodeWebSafe(
data: string,
charset: Utilities.Charset
): string
/**
* Compute a digest using the specified algorithm on the specified Byte[] value.
*
*
* var input = Utilities.base64Decode("aW5wdXQgdG8gaGFzaA0K") // == base64encode("input to hash")
* var digest = Utilities.computeDigest(Utilities.DigestAlgorithm.MD5, input);
* Logger.log(digest);
*
*
* @param algorithm - a DigestAlgorithm to use
* @param value - an input string value to compute a digest for
*
* @returns a byte[] representing the output digest
*/
function computeDigest(
algorithm: DigestAlgorithm,
value: number[]
): number[]
/**
* Compute a digest using the specified algorithm on the specified String value.
*
*
* var digest = Utilities.computeDigest(Utilities.DigestAlgorithm.MD5, "input to hash");
* Logger.log(digest);
*
*
* @param algorithm - a DigestAlgorithm to use
* @param value - an input string value to compute a digest for
*
* @returns a byte[] representing the output digest
*/
function computeDigest(
algorithm: DigestAlgorithm,
value: string
): number[]
/**
* Compute a digest using the specified algorithm on the specified String value with the
* given character set.
*
*
* var digest = Utilities.computeDigest(Utilities.DigestAlgorithm.MD5,
* "input to hash",
* Utilities.Charset.US_ASCII);
* Logger.log(digest);
*
*
* @param algorithm - a DigestAlgorithm to use
* @param value - an input string value to compute a digest for
* @param charset - a Charset representing the input character set
*
* @returns a byte[] representing the output digest
*/
function computeDigest(
algorithm: DigestAlgorithm,
value: string,
charset: Utilities.Charset
): number[]
/**
* Signs the provided value using HMAC-SHA256 with the given key.
*
*
* // This writes an array of bytes to the log.
* var input = Utilities.base64Decode("aW5wdXQgdG8gaGFzaA0K") // == base64encode("input to hash")
* var key = Utilities.base64Decode("a2V5"); // == base64encode("key")
* var signature = Utilities.computeHmacSha256Signature(input, key);
* Logger.log(signature);
*
*
* @param value - the input value to generate a hash for
* @param key - a key to use to generate the hash with
*
* @returns a byte[] representing the output signature
*/
function computeHmacSha256Signature(
value: number[],
key: number[]
): number[]
/**
* Signs the provided value using HMAC-SHA256 with the given key.
*
*
* // This writes an array of bytes to the log.
* var signature = Utilities.computeHmacSha256Signature("this is my input",
* "my key - use a stronger one");
* Logger.log(signature);
*
*
* @param value - the input value to generate a hash for
* @param key - a key to use to generate the hash with
*
* @returns a byte[] representing the output signature
*/
function computeHmacSha256Signature(
value: string,
key: string
): number[]
/**
* Signs the provided value using HMAC-SHA256 with the given key and character set.
*
*
* // This writes an array of bytes to the log.
* var signature = Utilities.computeHmacSha256Signature("this is my input",
* "my key - use a stronger one",
* Utilities.Charset.US_ASCII);
* Logger.log(signature);
*
*
* @param value - the input value to generate a hash for
* @param key - a key to use to generate the hash with
* @param charset - a Charset representing the input character set
*
* @returns a byte[] representing the output signature
*/
function computeHmacSha256Signature(
value: string,
key: string,
charset: Utilities.Charset
): number[]
/**
* Compute a message authentication code using the specified algorithm on the specified key and
* value.
*
*
* // This writes an array of bytes to the log.
* var input = Utilities.base64Decode("aW5wdXQgdG8gaGFzaA0K") // == base64encode("input to hash")
* var key = Utilities.base64Decode("a2V5"); // == base64encode("key")
* var signature = Utilities.computeHmacSignature(Utilities.MacAlgorithm.HMAC_MD5, input, key);
* Logger.log(signature);
*
*
* @param algorithm - a MacAlgorithm algorithm to use to hash the input value
* @param value - the input value to generate a hash for
* @param key - a key to use to generate the hash with
*
* @returns a byte[] representing the output signature
*/
function computeHmacSignature(
algorithm: Utilities.MacAlgorithm,
value: number[],
key: number[]
): number[]
/**
* Compute a message authentication code using the specified algorithm on the specified key and
* value.
*
*
* // This writes an array of bytes to the log.
* var signature = Utilities.computeHmacSignature(Utilities.MacAlgorithm.HMAC_MD5,
* "input to hash",
* "key");
* Logger.log(signature);
*
*
* @param algorithm - a MacAlgorithm algorithm to use to hash the input value
* @param value - the input value to generate a hash for
* @param key - a key to use to generate the hash with
*
* @returns a byte[] representing the output signature
*/
function computeHmacSignature(
algorithm: Utilities.MacAlgorithm,
value: string,
key: string
): number[]
/**
* Compute a message authentication code using the specified algorithm on the specified key and
* value.
*
*
* // This writes an array of bytes to the log.
* var signature = Utilities.computeHmacSignature(Utilities.MacAlgorithm.HMAC_MD5,
* "input to hash",
* "key",
* Utilities.Charset.US_ASCII);
* Logger.log(signature);
*
*
* @param algorithm - a MacAlgorithm algorithm to use to hash the input value
* @param value - the input value to generate a hash for
* @param key - a key to use to generate the hash with
* @param charset - a Charset representing the input character set
*
* @returns a byte[] representing the output signature
*/
function computeHmacSignature(
algorithm: Utilities.MacAlgorithm,
value: string,
key: string,
charset: Utilities.Charset
): number[]
/**
* Signs the provided value using RSA-SHA1 with the given key.
*
*
* // This writes an array of bytes to the log.
* var signature = Utilities.computeRsaSha1Signature("this is my input",
* "-----BEGIN PRIVATE KEY-----\nprivatekeyhere\n-----END PRIVATE KEY-----\n");
* Logger.log(signature);
*
*
* @param value - The input value to generate a hash for.
* @param key - A PEM formatted key to use to generate the signature.
*
* @returns A byte[] representing the output signature.
*/
function computeRsaSha1Signature(
value: string,
key: string
): number[]
/**
* Signs the provided value using RSA-SHA1 with the given key and charset.
*
*
* // This writes an array of bytes to the log.
* var signature = Utilities.computeRsaSha1Signature("this is my input",
* "-----BEGIN PRIVATE KEY-----\nprivatekeyhere\n-----END PRIVATE KEY-----\n"
* Utilities.Charset.US_ASCII);
* Logger.log(signature);
*
*
* @param value - The input value to generate a hash for.
* @param key - A PEM formatted key to use to generate the signature.
* @param charset - A Charset representing the input character set.
*
* @returns A byte[] representing the output signature.
*/
function computeRsaSha1Signature(
value: string,
key: string,
charset: Utilities.Charset
): number[]
/**
* Signs the provided value using RSA-SHA256 with the given key.
*
*
* // This writes an array of bytes to the log.
* var signature = Utilities.computeRsaSha256Signature("this is my input",
* "-----BEGIN PRIVATE KEY-----\nprivatekeyhere\n-----END PRIVATE KEY-----\n");
* Logger.log(signature);
*
*
* @param value - the input value to generate a hash for
* @param key - a PEM formatted key to use to generate the signature
*
* @returns a byte[] representing the output signature
*/
function computeRsaSha256Signature(
value: string,
key: string
): number[]
/**
* Signs the provided value using RSA-SHA256 with the given key.
*
*
* // This writes an array of bytes to the log.
* var signature = Utilities.computeRsaSha256Signature("this is my input",
* "-----BEGIN PRIVATE KEY-----\nprivatekeyhere\n-----END PRIVATE KEY-----\n");
* Logger.log(signature);
*
*
* @param value - the input value to generate a hash for
* @param key - a PEM formatted key to use to generate the signature
* @param charset - a Charset representing the input character set
*
* @returns a byte[] representing the output signature
*/
function computeRsaSha256Signature(
value: string,
key: string,
charset: Utilities.Charset
): number[]
/**
* Signs the provided value using the specified RSA algorithm with the given key.
*
*
* // This writes an array of bytes to the log.
* var signature = Utilities.computeRsaSignature(Utilities.RsaAlgorithm.RSA_SHA_256,
* "this is my input",
* "-----BEGIN PRIVATE KEY-----\nprivatekeyhere\n-----END PRIVATE KEY-----\n");
* Logger.log(signature);
*
*
* @param algorithm - A RsaAlgorithm algorithm to use to hash the input value.
* @param value - The input value to generate a hash for.
* @param key - A PEM formatted key to use to generate the signature.
*
* @returns A byte[] representing the output signature.
*/
function computeRsaSignature(
algorithm: Utilities.RsaAlgorithm,
value: string,
key: string
): number[]
/**
* Signs the provided value using the specified RSA algorithm with the given key and charset.
*
*
* // This writes an array of bytes to the log.
* var signature = Utilities.computeRsaSignature(Utilities.RsaAlgorithm.RSA_SHA_256,
* "this is my input",
* "-----BEGIN PRIVATE KEY-----\nprivatekeyhere\n-----END PRIVATE KEY-----\n",
* Utilities.Charset.US_ASCII);
* Logger.log(signature);
*
*
* @param algorithm - A RsaAlgorithm algorithm to use to hash the input value.
* @param value - The input value to generate a hash for.
* @param key - A PEM formatted key to use to generate the signature.
* @param charset - A Charset representing the input character set.
*
* @returns A byte[] representing the output signature.
*/
function computeRsaSignature(
algorithm: Utilities.RsaAlgorithm,
value: string,
key: string,
charset: Utilities.Charset
): number[]
/**
* Formats date according to specification described in Java SE SimpleDateFormat class. Please
* visit the specification at
* http://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html
*
*
* // This formats the date as Greenwich Mean Time in the format
* // year-month-dateThour-minute-second.
* var formattedDate = Utilities.formatDate(new Date(), "GMT", "yyyy-MM-dd'T'HH:mm:ss'Z'");
* Logger.log(formattedDate);
*
*
* @param date - a Date to format as a String
* @param timeZone - the output timezone of the result
* @param format - a format per the SimpleDateFormat specification
*
* @returns the input date as a formatted string
*/
function formatDate(
date: Date,
timeZone: string,
format: string
): string
/**
* Performs sprintf-like string formatting using '%'-style format strings.
*
*
* // " 123.456000"
* Utilities.formatString('%11.6f', 123.456);
*
* // " abc"
* Utilities.formatString('%6s', 'abc');
*
*
* @param template - The format string that controls what gets returned.
* @param args - Objects to use to fill in the '%' placeholders in the template.
*
* @returns the formatted string.
*/
function formatString(
template: string,
...args: Array