util methods

crackURL

Breaks a URL into its component parts.

Beginning with version 9.0, util.crackURL can break a URL that uses Internet Protocol version 6 (IPv6) addressing. The return object for util.crackURL includes an additional property, nURLType, to help determine the IP type of the URL being passed to the argument of util.crackURL.

No effort is made to determine the IP type if a direct URL is not used and the corresponding DNS name is used.

Parameters

Returns

An object containing the following properties:

This method throws a parameter error if the parameter is missing, the URL is not well-formed, or the URL scheme is not file, http, or https.

Example 1

The following code

   util.crackURL("http://example.org/myPath?name0=value0&name1=value1#frag");

would return

   {

      cScheme: "http",

      cHost: "example.org",

      nPort: 80,

      cPath: "/myPath",

      cQuery: "name0=value0&name1=value1",

      cFragment: "frag"

   }

Example 2 (Version 9.0)

Version 9.0 can break a URL into its components when the URL uses version 6 Internet Protocol.

var a = util.crackURL("http://[2001:1890:110b:15ce:250:56ff:febb:6111]/Ex");

if ( a.nURLType == 1 )

   console.println("host = [" + a.cHost + "]");

else

   console.println("host = " + a.cHost);

iconStreamFromIcon

Converts an XObject-based Icon object into an Icon Stream object.

Parameters

Returns

Icon Stream object

This method allows an icon obtained from the Doc importIcon or getIcon methods to be used in a method such as app.addToolButton, which would otherwise accept only an Icon Stream object as an input parameter.

Example

Import an icon into the document-level named icons tree and add a toolbutton to the application.

   this.importIcon("myIcon", "/C/temp/myIcon.jpg", 0);

   var oIcon = util.iconStreamFromIcon(this.getIcon("myIcon"));

   app.addToolButton({

      cName: "myButton",

      oIcon: oIcon,

      cExec: "console.println('My Button!');",
      cTooltext: "My button!",

      nPos: 0

   });

printd

Returns a date using a specified format.

Parameters

Returns

The formatted date string.

cFormat String Patterns

Example 1

Format the current date in long format:

   var d = new Date();

   console.println("Today is " + util.printd("mmmm dd, yyyy", d));

Example 2 (Acrobat 5.0)

Display the date in a local format

   console.println(util.printd(2, new Date() ));

Example 3 (Acrobat 7.0)

Use the XFA-Picture Clause to write the current date to the console.

   // Execute in console

   console.println(

      util.printd("EEE, 'the' D 'of' MMMM, YYYY", new Date(), true));

   // The output on this day is

   Tue, the 13 of July, 2004

Locale-Sensitive Picture Clauses. Normally processing of picture clauses occurs in the ambient locale. It is possible, however, to indicate that picture processing be done in a specific locale. This is of use when formatting or parsing data that is locale-specific and different from the ambient locale. The syntax for this extension to compound picture clauses is:

   category-name(locale-name){picture-symbols}

The code executed in the console,

   util.printd("date(fr){DD MMMM, YYYY}", new Date(), true)

yields the output on this day,

   13 juillet, 2004

The XFA-Picture Clause gives extensive support for Chinese, Chinese (Taiwan), Japanese, and Korean (CCJK) times and dates. The example below, a custom format script of a text field, gives the current date formatted for a Japanese locale.

   event.value = util.printd("date(ja){ggYY/M/D}", new Date(), true)

printf

Formats one or more arguments as a string according to a format string. It is similar to the C function of the same name. This method converts and formats incoming arguments into a result string according to a format string (cFormat).

The format string consists of two types of objects:

• Ordinary characters, which are copied to the result string.

• Conversion specifications, each of which causes conversion and formatting of the next successive argument to printf.

Each conversion specification is constructed as follows:

   %[,nDecSep][cFlags][nWidth][.nPrecision]cConvChar

The following table describes the components of a conversion specification.

Parameters

Note:The util.printf function does not accept an object literal with properties that contain the arguments. Arguments are entered in the usual comma-delimited list.

Returns

A result string formatted as specified.

Example

Take an irrational number and display it using various formats of util.printf.

   var n = Math.PI * 100;

   console.clear();

   console.show();

   console.println(util.printf("Decimal format: %d", n));

   console.println(util.printf("Hex format: %x", n));

   console.println(util.printf("Float format: %.2f", n));

   console.println(util.printf("String format: %s", n));

The output of the above script is as follows:

   Decimal format: 314

   Hex format: 13A

   Float format: 314.16

   String format: 314.159265358979

printx

Formats a source string, cSource, according to a formatting string, cFormat. A valid format for cFormat is any string that may contain special masking characters:

Parameters

Returns

The formatted string.

Example

Format a string as a U.S. telephone number.

   var v = "aaa14159697489zzz";

   v = util.printx("9 (999) 999-9999", v);

   console.println(v);

readFileIntoStream

.Loads an external file into a JavaScript stream, optionally base64 encodes it, and returns the content as a base64 encoded stream.

Parameters

Returns

The File content as a ReadStream object that is optionally base 64-encoded.

Example

Assume there is a text field myField in this document. This example reads the contents of a file c:/data/myData.txt in a ReadStream object, converts it to a string, and displays it in the multiline text field.

var rStream = util.readFileIntoStream("/c/data/myData.txt");

var cFile = util.stringFromStream(rStream);

this.getField("myTextField").value = cFile;

scand

Converts a date into a JavaScript Date object according to the rules of a format string. This routine is much more flexible than using the date constructor directly.

Note:Given a two-digit year for input, scand uses the date horizon heuristic to resolve the ambiguity. If the year is less than 50, it is assumed to be in the 21st century (that is, add 2000). If it is greater than or equal to 50, it is in the 20th century (add 1900).

The supplied date cDate should be in the same format as described by cFormat.

Parameters

Returns

The converted Date object, or null if the conversion fails.

Example 1

   /* Turn the current date into a string. */

   var cDate = util.printd("mm/dd/yyyy", new Date());

   console.println("Today’s date: " + cDate);

   /* Parse it back into a date. */

   var d = util.scand("mm/dd/yyyy", cDate);

   /* Output it in reverse order. */

   console.println("Yet again: " + util.printd("yyyy mmm dd", d));

Example 2

Retrieve a text field value, see if it is a date of the acceptable format, then report results in an alert box or the console window.

The method returns null if the conversions fails, which can occur if the user inputs a data different than what is expected. In this case, test the return value for null.

   var d= util.scand("mm/dd/yyyy", this.getField("myDate").value);

      if ( d== null )

         app.alert("Please enter a valid date of the form" +
            " \"mm/dd/yyyy\".")

      else {

         console.println("You entered the date: "

            + util.printd("mmmm dd, yyyy",d));

   }

spansToXML

Converts an array of Span objects into an XML(XFA) String as described in the PDF Reference.

Parameters

Returns

String

Example

Get the value of a rich text field, turns all of the text blue, converts it to an XML string and then prints it to the console.

   var f = getField("Text1");

   var spans = f.richValue;

   for(var index = 0; index < spans.length; index++)

      spans[index].textColor = color.blue;

   console.println(util.spansToXML(spans));

streamFromString

Converts a string to a ReadStream object.

Parameters

Returns

ReadStream object

Example

Take the response given in a text field of this document and append it to an attached document.

   var v = this.getField("myTextField").value;

   var oFile = this.getDataObjectContents("MyNotes.txt");

   var cFile = util.stringFromStream(oFile, "utf-8");

   cFile += "\r\n" + cFile;

   oFile = util.streamFromString( cFile, "utf-8");

   this.setDataObjectContents("MyNotes.txt", oFile);

This example uses the Doc methods getDataObjectContents and setDataObjectContents and util.stringFromStream.

stringFromStream

Converts a ReadStream object to a string.

Parameters

Returns

String

Example

Assume there is a text file embedded in this document. This example reads the contents of the attachment and displays it in the multiline text field.

   var oFile = this.getDataObjectContents("MyNotes.txt");

   var cFile = util.stringFromStream(oFile, "utf-8");

   this.getField("myTextField").value = cFile;

This example uses getDataObjectContents to get the file stream of the attached document.

xmlToSpans

Converts an XML (XFA) string, as described in the PDF Reference, to an array of Span objects suitable for specifying as the richValue or richContents of a field or annotation.

Parameters

Returns

An Array of Span objects

Example

Get the rich text string from “Text1”, convert it to XML, then convert it back to an array of Span objects and repopulate the text field.

   var f = getField("Text1");

   var spans = f.richValue;

   var str = util.spansToXML(spans);

   var spans = util.xmlToSpans(str);

   f.richValue = spans;