Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

util

util is a static object that provides various utility functions for formatting dates, numbers, strings, and handling file streams.

methods

printd

Secure
No

Formats a date according to a specified format string.

util.printd(cFormat, oDate, bXFAPicture)

cFormat: Format string for the date. Uses standard date format patterns where:

  • m - Month (1-12)
  • mm - Month with leading zero (01-12)
  • mmm - Abbreviated month name
  • mmmm - Full month name
  • d - Day (1-31)
  • dd - Day with leading zero (01-31)
  • yy - Two digit year
  • yyyy - Four digit year
  • h - Hour (12-hour format)
  • hh - Hour with leading zero (12-hour format)
  • H - Hour (24-hour format)
  • HH - Hour with leading zero (24-hour format)
  • M - Minute
  • MM - Minute with leading zero
  • s - Second
  • ss - Second with leading zero
  • tt - AM/PM designator

oDate: JavaScript Date object to format

bXFAPicture: [optional] Not used by Revu. Default is false

Returns the formatted date string

example:

var d = new Date()
console.println(util.printd("mm/dd/yyyy", d)) // Prints "01/15/2024"
console.println(util.printd("mmmm d, yyyy", d)) // Prints "January 15, 2024"
console.println(util.printd("yyyy-mm-dd HH:MM:ss", d)) // Prints "2024-01-15 14:30:45"

printf

Secure
No

Formats one or more values according to a format string, similar to the C printf function.

util.printf(cFormat, ...arguments)

cFormat: Format string containing format specifiers

arguments: Values to be formatted according to the format string

Format specifiers:

  • %s - String
  • %d - Integer
  • %f - Floating point number
  • %x - Hexadecimal (uppercase)
  • %,0d - Integer with thousands separator
  • %,1d - Integer without thousands separator
  • %,2d - Integer with period as thousands separator
  • %,3d - Integer with period as thousands separator and comma as decimal
  • %,4d - Integer with apostrophe as thousands separator

Additional format options:

  • Width: Number specifying minimum field width (e.g., %10s)
  • Precision: . followed by number for decimal places (e.g., %.2f)
  • Flags:
    • + - Always show sign for numbers
    • - Prefix positive numbers with space
    • 0 - Pad with zeros
    • # - Alternate form

Returns the formatted string

example:

console.println(util.printf("Name: %s, Age: %d", "John", 25))
// Prints "Name: John, Age: 25"

console.println(util.printf("Price: $%,0.2f", 1234.5))
// Prints "Price: $1,234.50"

console.println(util.printf("Hex: %x", 255))
// Prints "Hex: FF"

console.println(util.printf("%+d, % d, %05d", 42, 42, 42))
// Prints "+42,  42, 00042"

printx

Secure
No

Formats a string according to a template pattern, useful for formatting phone numbers, social security numbers, and other structured data.

util.printx(cFormat, cSource)

cFormat: Template string with special characters:

  • ? - Matches any character
  • X - Matches any alphanumeric character (skips non-alphanumeric)
  • A - Matches any letter (skips non-letters)
  • 9 - Matches any digit (skips non-digits)
  • * - Matches all remaining characters
  • \ - Escape character for literals
  • > - Converts subsequent characters to uppercase
  • < - Converts subsequent characters to lowercase
  • = - Preserves case of subsequent characters

cSource: Source string to format

Returns the formatted string

example:

console.println(util.printx("(999) 999-9999", "5551234567"))
// Prints "(555) 123-4567"

console.println(util.printx("999-99-9999", "123456789"))
// Prints "123-45-6789"

console.println(util.printx(">AAA-999", "abc123"))
// Prints "ABC-123"

console.println(util.printx("\\*999\\*", "456"))
// Prints "*456*"

console.println(util.printx("?-?-?", "ABC"))
// Prints "A-B-C"

readFileIntoStream

Secure
Yes

Reads a file from disk into a stream. This function requires elevated privileges.

util.readFileIntoStream(cDIPath, bEncodeBase64)

cDIPath: [optional] Device-independent path to the file. If not specified, the user is prompted to select a file.

bEncodeBase64: [optional] When true, encodes the file contents as Base64. Default is false

Returns a ReadStream object containing the file contents, or null if the operation fails

example:

// Prompt user to select a file
var stream = util.readFileIntoStream()
if (stream) {
    var contents = util.stringFromStream(stream)
    console.println(contents)
}

// Read specific file (requires elevated privileges)
var stream = util.readFileIntoStream("/c/data/config.txt")

// Read and encode as Base64
var stream = util.readFileIntoStream("/c/data/image.png", true)

scand

Secure
No

Parses a date string according to a specified format and returns a Date object.

util.scand(cFormat, cDate)

cFormat: Format string describing the expected date format (uses same format as printd)

cDate: String containing the date to parse

Returns a JavaScript Date object if parsing succeeds, throws an error if parsing fails

example:

var date = util.scand("mm/dd/yyyy", "01/15/2024")
console.println(date) // Date object for January 15, 2024

var date2 = util.scand("yyyy-mm-dd", "2024-01-15")
console.println(date2) // Date object for January 15, 2024

var date3 = util.scand("mmmm d, yyyy", "January 15, 2024")
console.println(date3) // Date object for January 15, 2024

streamFromString

Secure
No

Creates a stream from a string with the specified character encoding.

util.streamFromString(cString, cCharSet)

cString: String to convert to a stream

cCharSet: [optional] Character encoding. Default is "utf-8". Supported values:

  • "utf-8"
  • "utf-16"
  • "Shift-JIS"
  • "BigFive"
  • "GBK"
  • "UHC"

Returns a ReadStream object containing the encoded string

example:

var stream = util.streamFromString("Hello World")
// Creates a UTF-8 encoded stream

var stream2 = util.streamFromString("こんにちは", "Shift-JIS")
// Creates a Shift-JIS encoded stream

// Use with other functions that expect streams
this.setDataObjectContents("data.txt", stream)

stringFromStream

Secure
No

Converts a stream to a string using the specified character encoding.

util.stringFromStream(oStream, cCharSet)

oStream: ReadStream object to convert

cCharSet: [optional] Character encoding. Default is "utf-8". Supported values:

  • "utf-8"
  • "utf-16"
  • "Shift-JIS"
  • "BigFive"
  • "GBK"
  • "UHC"

Returns the decoded string

example:

// Read a data object as a string
var stream = this.getDataObjectContents("textfile.txt")
var text = util.stringFromStream(stream)
console.println(text)

// Read with specific encoding
var stream2 = this.getDataObjectContents("japanese.txt")
var text2 = util.stringFromStream(stream2, "Shift-JIS")
console.println(text2)