Package com.adobe.xfa.ut

Class PictureFmt

java.lang.Object
com.adobe.xfa.ut.PictureFmt
public final class PictureFmt extends Object
The PictureFmt class defines methods to parse and format data according to XFA picture patterns. Here's a snippet of code illustrating its use to format a date string: 

     import com.adobe.xfa.ut.PictureFmt;
     ...
     StringBufer sResult = new StringBuilder();
     PictureFmt oFmt = new PictureFmt("en"); 
     if (oFmt.parse("28/2/2000", "D/M/YYYY", sResult)) 
         oFmt.format(sResult.toString(), "EEEE', the 'D' of 'MMMM', 'YYYY", sResult) 
     ...

PictureFmt also defines methods to validate picture patterns. Specifically, the methods

isZeroPictureValid(String), and,
  • isNullPictureValid(String). are used for validating the syntax of the given source for each of the six categories of pictures. This includes validating the well-formedness of patterns like category{subpicture} and category(locale){subpicture}, validating the well-formedness of literals, and ensuring the given source symbols all belong to one category of picture. As an example, the time picture pattern: 
    
     h:MM:SS 'o'clock 'A X
    is syntactically invalid - a quote is missing and X is not a valid time picture symbol.

    PictureFmt also defines methods to semantically validate picture patterns. The methods

    are used for semantially validating the given picture. This means that the combination of XFA symbols constitutes a valid XFA picture pattern. A time picture pattern like: 
    
     h:MM:SS 'o''clock 'Z
    is semantically invalid when used to parse time input -- requesting a time from a 12-hour clock without the meridiem could never yield a correct time value. A date picture pattern like: EEEE, MMMM YYYY is semantically invalid when used to parse date input -- requesting a date without the day of the month could never yield a correct date value.

    Do note however, that semantically invalid pictures patterns are used in output formatting in acceptable circumstances. So apply these method with discretion.

    • Constructor Details

      • PictureFmt

        public PictureFmt(String sLocale)
        Instantiates an PictureFmt object.
        Parameters:
        sLocale - the locale name.

    • Method Details

      • resolveRange

        public static Point resolveRange(String s, int startIndex, int endIndex)

      • format

        public boolean format(String sSource, String sPicture, StringBuilder sResult)
        Formats a given data source according to the given picture.
        Parameters:
        sSource - the source data in canonical format.
        sPicture - the formatting picture.
        sResult - the resulting string, which may be empty upon error.
        Returns:
        boolean true if successful and false otherwise.

      • parse

        public String parse(String sSource, String sPicture, BooleanHolder pbSuccess)
        Parses a given data source according to the given picture.
        Parameters:
        sSource - the source data.
        sPicture - the parsing picture.
        pbSuccess - the canonical result.
        Returns:
        the string result.

      • FF99ToXFA

        public static String FF99ToXFA(String sPicture)
        Converts a F99 picture to an equivalent XFA picture. F99 pictures contain either double quote enclosed literals, or single quote enclosed literals. Change all to single quote enclosed literals, suitably escaping any embedded double quotes.
        Parameters:
        sPicture - the source picture.
        Returns:
        the equivalent XFA picture.

      • formatCompound

        public static boolean formatCompound(String sSource, String sPicture, String sLocale, StringBuilder sResult)
        Formats a given data source according to the given compound picture under the given locale.
        Parameters:
        sSource - the source data.
        sPicture - the compound picture.
        sLocale - the locale name.
        sResult - the resulting string, which may be empty upon error.
        Returns:
        This method is not operational!

      • formatDate

        public static boolean formatDate(String sSource, String sPicture, String sLocale, StringBuilder sResult, boolean bAsLocal)
        Formats a given data source according to the given date picture under the given locale.
        Parameters:
        sSource - the source data.
        sPicture - the date picture.
        sLocale - the locale name.
        sResult - the resulting string, which may be empty upon error.
        bAsLocal - interpret the source data as a local date when true, and a GMT date when false.
        Returns:
        boolean true upon success and false otherwise.

      • formatDateTime

        public static boolean formatDateTime(String sSource, String sPicture, String sDateMask, String sTimeMask, String sLocale, StringBuilder sResult, boolean bAsLocal)
        Formats a given data source according to the given datetime picture under the given locale.
        Parameters:
        sSource - the source data.
        sPicture - the datetime picture.
        sDateMask - the date sub-picture.
        sTimeMask - the time sub-picture.
        sLocale - the locale name.
        sResult - the resulting string, which may be empty upon error.
        bAsLocal - interpret the data source as locale datetime when true, and GMT datetime when false.
        Returns:
        boolean true upon success and false otherwise.

      • formatNull

        public static boolean formatNull(String sSource, String sPicture, String sLocale, StringBuilder sResult)
        Formats a given data source according to the given null picture under the given locale.
        Parameters:
        sSource - the source data.
        sPicture - the null picture.
        sLocale - the locale name.
        sResult - the resulting string, which may be empty upon error.
        Returns:
        boolean true upon success and false otherwise.

      • formatNumeric

        public static boolean formatNumeric(String sSource, String sPicture, String sLocale, StringBuilder sResult)
        Formats a given data source according to the given numeric picture under the given locale.
        Parameters:
        sSource - the source data.
        sPicture - the numeric picture.
        sLocale - the locale name.
        sResult - the resulting string, which may be empty upon error.
        Returns:
        boolean true upon success and false otherwise.

      • formatText

        public static boolean formatText(String sSource, String sPicture, String sLocale, StringBuilder sResult)
        Formats a given data source according to the given text picture under the given locale.
        Parameters:
        sSource - the source data.
        sPicture - the text picture.
        sLocale - the locale name.
        sResult - the resulting string, which may be empty upon error.
        Returns:
        boolean true upon success and false otherwise.

      • formatTime

        public static boolean formatTime(String sSource, String sPicture, String sLocale, StringBuilder sResult, boolean bAsLocal)
        Formats a given data source according to the given time picture under the given locale.
        Parameters:
        sSource - the source data.
        sPicture - the time picture.
        sLocale - the locale name.
        sResult - the resulting string, which may be empty upon error.
        bAsLocal - interpret the data source as local time when true, and a GMT time when false.
        Returns:
        boolean true upon success and false otherwise.

      • formatZero

        public static boolean formatZero(String sSource, String sPicture, String sLocale, StringBuilder sResult)
        Formats a given data source according to the given zero picture under the given locale.
        Parameters:
        sSource - the source data. It must be empty or zero!
        sPicture - the zero picture.
        sLocale - the locale name.
        sResult - the resulting string, which may be empty upon error.
        Returns:
        boolean true upon success and false otherwise.

      • getAlternates

        public static boolean getAlternates(String sSource, List<String> oAlternates)
        Gets all the picture alternatives.
        Parameters:
        sSource - the source picture. Alternate pictures are each separated by the vertical bar '|' character.
        oAlternates - the object to be populated with all the alternate pictures found in the source.
        Returns:
        boolean true upon success and false if the source picture is invalid.

      • getLocaleFromPicture

        public static boolean getLocaleFromPicture(String sPicture, String sCategory, StringBuilder sLocale)
        Gets the locale given a valid picture and category.
        Parameters:
        sPicture - the valid picture.
        sCategory - the picture category: one of "date", "time", "num", "text", "null" or "zero".
        sLocale - the returned locale.
        Returns:
        boolean true if the source picture is semantically valid, and false otherwise.

      • hasSubPicture

        public static boolean hasSubPicture(String sPicture, int nPictIndex, StringBuilder sCategory, StringBuilder sLocale, StringBuilder sSubMask)
        Determines if the given picture has a sub-picture. If so, the sub-picture's components are returned. Subpictures are of the form: category{subpicture} or category(locale){subpicture}.
        Parameters:
        sPicture - the picture.
        nPictIndex - the starting picture index.
        sCategory - the picture's category.
        sLocale - the picture's locale.
        sSubMask - the picture's sub-picture.
        Returns:
        boolean true if there's a sub-picture, and false otherwise.

      • isDatePicture

        public static boolean isDatePicture(String sPicture)
        Determines if the given picture is a date picture.
        Parameters:
        sPicture - the source picture.
        Returns:
        boolean true if the source picture is syntactically valid, and false otherwise.

      • isDatePictureValid

        public static boolean isDatePictureValid(String sPicture)
        Determines if the given date picture is (semantically) valid.
        Parameters:
        sPicture - the date picture.
        Returns:
        boolean true if the source picture is semantically valid, and false otherwise.

      • isDateTimePicture

        public static boolean isDateTimePicture(String sPicture, StringBuilder sDateMask, StringBuilder sTimeMask)
        Determines if the given picture is a date time picture.
        Parameters:
        sPicture - the source picture.
        sDateMask - the returned date picture found in the given source picture.
        sTimeMask - the returned time picture found in the given source picture.
        Returns:
        boolean true if the source picture is syntactically valid, and false otherwise.

      • isDateTimePictureValid

        public static boolean isDateTimePictureValid(String sPicture)
        Determimes if the given datetime picture is (semantically) valid.
        Parameters:
        sPicture - the datetime picture.
        Returns:
        boolean true if the source picture is semantically valid, and false otherwise.

      • isNullPicture

        public static boolean isNullPicture(String sPicture)
        Determines if the given picture is a null picture.
        Parameters:
        sPicture - the source picture.
        Returns:
        boolean true if the source picture is syntactically valid, and false otherwise.

      • isEmptyPicture

        public static boolean isEmptyPicture(String sPicture)
        Determines if the given picture is an empty picture.
        Parameters:
        sPicture - the source picture.
        Returns:
        boolean true if the source picture is syntactically valid, and false otherwise.

      • isNullPictureValid

        public static boolean isNullPictureValid(String sPicture)
        Determimes if the given null picture is (semantically) valid.
        Parameters:
        sPicture - the null picture.
        Returns:
        boolean true if the source picture is semantically valid, and false otherwise.

      • isNumericPicture

        public static boolean isNumericPicture(String sPicture)
        Determimes if the given picture is a numeric picture.
        Parameters:
        sPicture - the source picture.
        Returns:
        boolean true if the source picture is syntactically valid, and false otherwise.

      • isNumericPictureValid

        public static boolean isNumericPictureValid(String sPicture)
        Determimes if the given numeric picture is (semantically) valid.
        Parameters:
        sPicture - the numeric picture.
        Returns:
        boolean true if the source picture is semantically valid, and false otherwise.

      • isSubPicture

        public static boolean isSubPicture(String sPicture, int nPictIndex, StringBuilder sCategory, StringBuilder sLocale, StringBuilder sSubMask)
        Determimes if the given picture has a sub-picture, and if so, returns the picture's category, locale, and sub-picture.
        Parameters:
        sPicture - the source picture.
        nPictIndex - the starting character index within the given source picture.
        sCategory - the picture's category.
        sLocale - the picture's locale.
        sSubMask - the picture's sub-picture.
        Returns:
        boolean true if the picture is a locale sensitive picture and false otherwise.

      • isTextPicture

        public static boolean isTextPicture(String sPicture)
        Determines if the given picture is a text picture.
        Parameters:
        sPicture - the source picture.
        Returns:
        boolean true if the source picture is syntactically valid, and false otherwise.

      • isTextPictureValid

        public static boolean isTextPictureValid(String sPicture)
        Determines if the given text picture is (semantically) valid.
        Parameters:
        sPicture - the text picture.
        Returns:
        boolean true if the source picture is semantically valid, and false otherwise.

      • isTimePicture

        public static boolean isTimePicture(String sPicture)
        Determines if the given picture is a time picture.
        Parameters:
        sPicture - the source picture.
        Returns:
        boolean true if the source picture is syntactically valid, and false otherwise.

      • isTimePictureValid

        public static boolean isTimePictureValid(String sPicture)
        Determines if the given time picture is (semantically) valid.
        Parameters:
        sPicture - the time picture.
        Returns:
        boolean true if the source picture is semantically valid, and false otherwise.

      • isZeroPicture

        public static boolean isZeroPicture(String sPicture)
        Determines if the given picture is a zero picture.
        Parameters:
        sPicture - the source picture.
        Returns:
        boolean true if the source picture is syntactically valid, and false otherwise.

      • isZeroPictureValid

        public static boolean isZeroPictureValid(String sPicture)
        Determines if the given zero picture is (semantically) valid.
        Parameters:
        sPicture - the zero picture.
        Returns:
        boolean true if the source picture is semantically valid, and false otherwise.

      • parseCompound

        public static boolean parseCompound(String sSource, String sPicture, String sLocale, StringHolder sResult)
        Parses a given data source according to the given compound picture under the given locale.
        Parameters:
        sSource - the source data.
        sPicture - the compound picture.
        sLocale - the locale name.
        sResult - the resulting canonical string, which may be empty upon error.
        Returns:
        boolean true upon success and false otherwise.

      • parseDate

        public static boolean parseDate(String sSource, String sPicture, String sLocale, StringHolder sResult, boolean bAsLocal)
        Parses a given data source according to the given date picture under the given locale.
        Parameters:
        sSource - the source data.
        sPicture - the date picture.
        sLocale - the locale name.
        sResult - the resulting canonical string, which may be empty upon error.
        bAsLocal - return the canonical result as a local date when true, and as a GMT date when false.
        Returns:
        boolean true upon success and false otherwise.

      • parseDateTime

        public static boolean parseDateTime(String sSource, String sPicture, String sDateMask, String sTimeMask, String sLocale, StringHolder sResult, boolean bAsLocal)
        Parses a given data source according to the given datetime picture under the given locale.
        Parameters:
        sSource - the source data.
        sPicture - the datetime picture.
        sDateMask - the date sub-picture.
        sTimeMask - the time sub-picture.
        sLocale - the locale name.
        sResult - the resulting canonical string, which may be empty upon error.
        bAsLocal - return the canonical result as a local datetime when true, and as a GMT datetime value when false.
        Returns:
        boolean true upon success and false otherwise.

      • parseNull

        public static boolean parseNull(String sSource, String sPicture, String sLocale, StringHolder sResult)
        Parses a given data source according to the given null picture under the given locale.
        Parameters:
        sSource - the source data.
        sPicture - the null picture.
        sLocale - the locale name.
        sResult - the resulting canonical string, which may be empty upon error.
        Returns:
        boolean true upon success and false otherwise.

      • parseNumeric

        public static boolean parseNumeric(String sSource, String sPicture, String sLocale, StringHolder sResult)
        Parses a given data source according to the given numeric picture under the given locale.
        Parameters:
        sSource - the source data.
        sPicture - the numeric picture.
        sLocale - the locale name.
        sResult - the resulting canonical string, which may be empty upon error.
        Returns:
        boolean true upon success and false otherwise.

      • parseText

        public static boolean parseText(String sSource, String sPicture, String sLocale, StringHolder sResult)
        Parses a given data source according to the given text picture under the given locale.
        Parameters:
        sSource - the source data.
        sPicture - the text picture.
        sLocale - the locale name.
        sResult - the resulting canonical string, which may be empty upon error.
        Returns:
        boolean true upon success and false otherwise.

      • parseTime

        public static boolean parseTime(String sSource, String sPicture, String sLocale, StringHolder sResult, boolean bAsLocal)
        Parses a given data source according to the given time picture under the given locale.
        Parameters:
        sSource - the source data.
        sPicture - the time picture.
        sLocale - the locale name.
        sResult - the resulting canonical string, which may be empty upon error.
        Returns:
        boolean true upon success and false otherwise.

      • parseZero

        public static boolean parseZero(String sSource, String sPicture, String sLocale, StringHolder sResult)
        Parses a given data source according to the given zero picture under the given locale.
        Parameters:
        sSource - the source data.
        sPicture - the zero picture.
        sLocale - the locale name.
        sResult - the resulting canonical string, which may be empty upon error.
        Returns:
        boolean true upon success and false otherwise.