Package com.ilib

Class IString

  • public class IString
extends java.lang.Object
    IString Represents an international string. This type of string allows for a formatting syntax very similar to the javascript ilib syntax, so that strings can be shared between code in java or javascript.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected static java.lang.String CLOSED_BRACE  
      protected java.lang.String defaultChoice  
      static java.lang.String EMPTY_ITEM  
      protected IlibLocale locale  
      protected static java.lang.String NUMBER_SIGN  
      protected static java.lang.String OPENED_BRACE  
      protected java.util.ArrayList<java.util.regex.Pattern> patterns  
      protected java.util.Map<java.lang.String,​java.lang.String> plurals  
      protected java.util.ArrayList<java.lang.String> selectors  
      protected java.util.ArrayList<java.lang.String> strings  
      protected java.lang.String text  

    • Constructor Summary

      Constructors 
      Constructor Description
      IString​(java.lang.String text)
      Construct a new IString instance with the given text.
      IString​(java.lang.String text, IlibLocale locale)
      Construct a new IString instance with the given text and IlibLocale instance.
      IString​(java.lang.String text, java.lang.String locale)
      Construct a new IString instance with the given text and IlibLocale instance.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static java.lang.String format​(java.lang.String message, java.util.HashMap<java.lang.String,​java.lang.String> parameters)
      Static convenience method to format without an IString instance.
      java.lang.String format​(java.util.Map<java.lang.String,​java.lang.String> values)
      Format a string with the given named values.
      java.lang.String format​(org.json.JSONObject values)
      This is the same as format(Map) except the replacement values come from a JSON object instead of a map.
      java.lang.String formatChoice​(boolean reference, java.util.Map<java.lang.String,​java.lang.String> values)
      This is the same as formatChoice(double, Map) except that the type of the reference argument is boolean.
      java.lang.String formatChoice​(boolean reference, org.json.JSONObject values)
      This is the same as formatChoice(boolean, Map) except that the named replacement values come from a JSON object instead of a map.
      java.lang.String formatChoice​(double reference)
      This is the same as formatChoice(double, Map) but with null map.
      java.lang.String formatChoice​(double reference, java.util.Map<java.lang.String,​java.lang.String> values)
      Format a string as one of a choice of strings dependent on the value of a particular reference argument.
      java.lang.String formatChoice​(double reference, org.json.JSONObject values)
      This is the same as formatChoice(double, Map) except that the named replacement values come from a JSON object instead of a map.
      static java.lang.String formatChoice​(java.lang.String message, double reference)
      Static convenience method to format choices without an IString instance.
      static java.lang.String formatChoice​(java.lang.String message, double reference, java.util.HashMap<java.lang.String,​java.lang.String> parameters)
      Static convenience method to format choices without an IString instance.
      static java.lang.String formatChoice​(java.lang.String message, long reference)
      Static convenience method to format choices without an IString instance.
      static java.lang.String formatChoice​(java.lang.String message, long reference, java.util.HashMap<java.lang.String,​java.lang.String> parameters)
      Static convenience method to format choices without an IString instance.
      java.lang.String formatChoice​(java.lang.String reference, java.util.Map<java.lang.String,​java.lang.String> values)
      This is the same as formatChoice(double, Map) except that the type of the reference argument is a string which is matched against the regular expressions selectors in the choice string.
      java.lang.String formatChoice​(java.lang.String reference, org.json.JSONObject values)
      This is the same as formatChoice(String, Map) except that the named replacement values come from a JSON object instead of a map.
      protected int getBooleanSelector​(java.lang.String selector)  
      protected IString getChoice​(boolean reference)  
      protected IString getChoice​(double reference)  
      protected IString getChoice​(java.lang.String reference)  
      IlibLocale getLocale()
      Return locale associated with current IString instance.
      static boolean isNumeric​(java.lang.String str)  
      int length()
      Return the length of the given string in characters.
      protected void parseChoices()  
      void setLocale​(IlibLocale locale)
      Return locale of current IString instance.
      java.lang.String toString()  

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

    • Field Detail

      • text

        protected java.lang.String text

      • selectors

        protected java.util.ArrayList<java.lang.String> selectors

      • strings

        protected java.util.ArrayList<java.lang.String> strings

      • defaultChoice

        protected java.lang.String defaultChoice

      • patterns

        protected java.util.ArrayList<java.util.regex.Pattern> patterns

      • plurals

        protected java.util.Map<java.lang.String,​java.lang.String> plurals

    • Constructor Detail

      • IString

        public IString​(java.lang.String text)
        Construct a new IString instance with the given text.
        Parameters:
        text - the text to wrap

      • IString

        public IString​(java.lang.String text,
               java.lang.String locale)
        Construct a new IString instance with the given text and IlibLocale instance.
        Parameters:
        text - the text to wrap
        locale - current locale

      • IString

        public IString​(java.lang.String text,
               IlibLocale locale)
        Construct a new IString instance with the given text and IlibLocale instance.
        Parameters:
        text - the text to wrap
        locale - current locale

    • Method Detail

      • format

        public java.lang.String format​(java.util.Map<java.lang.String,​java.lang.String> values)
        Format a string with the given named values. The string can contain any text that a regular Java string can contain. Replacement parameters have the syntax: 
         {name}
        Where "name" can be any string surrounded by curly brackets. The value of "name" is taken from the values argument.

        Example: 

         int numObjects = 12;
 IString str = new IString("There are {num} objects.");
 HashMap values = new HashMap();
 values.put("num", Integer.toString(numObjects));  
 System.out.println(str.format(values));
        Would give the output: 
         There are 12 objects.
        If a property is missing from the value map, the replacement parameter substring is left untouched in the string, and a different set of parameters may be applied a second time. This way, different parts of the code may format different parts of the message that they happen to know about.

        Example: 

         int numObjects = 12;
 IString str = new IString("There are {num} objects in the {container}.");
 HashMap values = new HashMap();
 values.put("num", Integer.toString(numObjects));  
 System.out.println(str.format(values));
        Would give the output:

         There are 12 objects in the {container}.
        The result can then be formatted again with a different value map that specifies a value for the "container" property.
        Parameters:
        values - a set of named values
        Returns:
        the string with as many replacement parameters replaced with named values as possible

      • format

        public java.lang.String format​(org.json.JSONObject values)
        This is the same as format(Map) except the replacement values come from a JSON object instead of a map.
        Parameters:
        values - a set of named values in a JSON object
        Returns:
        the string with as many replacement parameters replaced with named values as possible

      • parseChoices

        protected void parseChoices()
                     throws java.text.ParseException
        Throws:
        java.text.ParseException

      • getBooleanSelector

        protected int getBooleanSelector​(java.lang.String selector)

      • getChoice

        protected IString getChoice​(boolean reference)
                     throws java.text.ParseException
        Throws:
        java.text.ParseException

      • getChoice

        protected IString getChoice​(java.lang.String reference)
                     throws java.text.ParseException
        Throws:
        java.text.ParseException

      • getChoice

        protected IString getChoice​(double reference)
                     throws java.text.ParseException
        Throws:
        java.text.ParseException

      • isNumeric

        public static boolean isNumeric​(java.lang.String str)

      • formatChoice

        public java.lang.String formatChoice​(double reference,
                                     java.util.Map<java.lang.String,​java.lang.String> values)
                              throws java.text.ParseException
        Format a string as one of a choice of strings dependent on the value of a particular reference argument.

        The syntax of the choice string is as follows. The string contains a series of choices separated by a vertical bar character "|". Each choice has a selector, which is a value or range of values to match and an optional operator, followed by a hash character "#", followed by the string to use if the reference argument matches the criteria.

        Example string: 

         int num = 2;
 IString str = new IString("0#There are no objects.|1#There is one object.|2#There are {number} objects.");
 HashMap values = new HashMap();
 values.put("number", Integer.toString(num));  
 System.out.println(str.formatChoice(num, values));
        Gives the output: 
         "There are 2 objects."
        The strings to format may contain replacement variables that will be formatted using the format(Map) method and the values argument as a source of values to use while formatting those variables.

        If the selector for a particular choice is empty, that choice will be used as the default one for use when none of the other choice's criteria match.

        Example string: 

         int num = 22;
 IString str = new IString("0#There are no objects.|1#There is one object.|#There are {number} objects.");
 HashMap values = new HashMap();
 values.put("number", Integer.toString(num));  
 System.out.println(str.formatChoice(num, values));
        Gives the output: 
         "There are 22 objects."
        If multiple selectors can match a given reference argument, the first one encountered in the string will be used. If no selectors match the reference argument, then the default choice will be used. If there is no default choice defined, then this method will return an empty string.

        Special Syntax

        For any choice format string, all of the selectors in the string should be of the same type. The available types are: numeric, boolean, or string/regexp. The type of the selectors is determined by the type of the reference argument.

        If the reference argument is numeric, then some special operator syntax can be used in the selectors to match numeric ranges.

        • >x - match any number that is greater than x
        • >=x - match any number that is greater than or equal to x
        • <x - match any number that is less than x
        • <=x - match any number that is less than or equal to x
        • start-end - match any number in the range [start,end)
        If the type of the reference argument is boolean, the strings "true", "on", "yes", "1", or "false", "off", "no", or "0" (without the quotes) may appear as the selectors.

        If the type of the reference argument is string, then the selectors may contain regular expressions, or just regular strings as if they were degenerate regexps.

        Parameters:
        reference - The reference value used to select the choice to use in the choice array
        values - The map of parameter values that replace the replacement variables in the string
        Returns:
        the formatted string
        Throws:
        java.text.ParseException

      • formatChoice

        public java.lang.String formatChoice​(double reference,
                                     org.json.JSONObject values)
                              throws java.text.ParseException
        This is the same as formatChoice(double, Map) except that the named replacement values come from a JSON object instead of a map.
        Parameters:
        reference - The reference value used to select the choice to use in the choice array
        values - The JSON object containing parameter values that replace the replacement variables in the string
        Returns:
        the formatted string
        Throws:
        java.text.ParseException
        See Also:
        formatChoice(double, Map)

      • formatChoice

        public java.lang.String formatChoice​(double reference)
                              throws java.text.ParseException
        This is the same as formatChoice(double, Map) but with null map.
        Parameters:
        reference - The reference value used to select the choice to use in the choice array
        Returns:
        the formatted string
        Throws:
        java.text.ParseException
        See Also:
        formatChoice(double, Map)

      • formatChoice

        public java.lang.String formatChoice​(boolean reference,
                                     java.util.Map<java.lang.String,​java.lang.String> values)
                              throws java.text.ParseException
        This is the same as formatChoice(double, Map) except that the type of the reference argument is boolean. In this case, the strings "true", "on", "yes", "1", or "false", "off", "no", or "0" (without the quotes) may appear as the selectors. If a choice string with boolean selectors is formatted with a numeric argument index instead, then the value of "false" is taken to be 0, and the value of true is taken to be 1.
        Parameters:
        reference - The reference value used to select the choice to use in the choice array
        values - The map of parameter values that replace the replacement variables in the string
        Returns:
        the formatted string
        Throws:
        java.text.ParseException
        See Also:
        formatChoice(double, Map)

      • formatChoice

        public java.lang.String formatChoice​(boolean reference,
                                     org.json.JSONObject values)
                              throws java.text.ParseException
        This is the same as formatChoice(boolean, Map) except that the named replacement values come from a JSON object instead of a map.
        Parameters:
        reference - The reference value used to select the choice to use in the choice array
        values - The JSON object containing parameter values that replace the replacement variables in the string
        Returns:
        the formatted string
        Throws:
        java.text.ParseException
        See Also:
        formatChoice(double, Map)

      • formatChoice

        public java.lang.String formatChoice​(java.lang.String reference,
                                     java.util.Map<java.lang.String,​java.lang.String> values)
                              throws java.text.ParseException
        This is the same as formatChoice(double, Map) except that the type of the reference argument is a string which is matched against the regular expressions selectors in the choice string. A choice is selected if the regular expression matches the reference argument. The first choice that has its regexp match the reference argument is the one that is selected. Remember to escape any "#" or "|" characters in the regular expression so that they do not conflict with the syntax of the choice format string.
        Parameters:
        reference - The reference value used to select the choice to use in the choice array
        values - The map of parameter values that replace the replacement variables in the string
        Returns:
        the formatted string
        Throws:
        java.text.ParseException
        See Also:
        formatChoice(double, Map)

      • formatChoice

        public java.lang.String formatChoice​(java.lang.String reference,
                                     org.json.JSONObject values)
                              throws java.text.ParseException
        This is the same as formatChoice(String, Map) except that the named replacement values come from a JSON object instead of a map.
        Parameters:
        reference - The reference value used to select the choice to use in the choice array
        values - The JSON object containing parameter values that replace the replacement variables in the string
        Returns:
        the formatted string
        Throws:
        java.text.ParseException
        See Also:
        formatChoice(double, Map)

      • length

        public int length()
        Return the length of the given string in characters.
        Returns:
        the length of the given string in characters

      • getLocale

        public IlibLocale getLocale()
        Return locale associated with current IString instance.
        Returns:
        current locale

      • setLocale

        public void setLocale​(IlibLocale locale)
        Return locale of current IString instance.
        Parameters:
        locale - locale to be used for plurals translation

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • formatChoice

        public static java.lang.String formatChoice​(java.lang.String message,
                                            long reference,
                                            java.util.HashMap<java.lang.String,​java.lang.String> parameters)
                                     throws java.text.ParseException
        Static convenience method to format choices without an IString instance.
        Parameters:
        message - string to format
        reference - reference value
        parameters - parameters to format into the string
        Returns:
        a formatted string
        Throws:
        java.text.ParseException - if the syntax of the choice format is wrong

      • formatChoice

        public static java.lang.String formatChoice​(java.lang.String message,
                                            double reference,
                                            java.util.HashMap<java.lang.String,​java.lang.String> parameters)
                                     throws java.text.ParseException
        Static convenience method to format choices without an IString instance.
        Parameters:
        message - string to format
        reference - reference value
        parameters - parameters to format into the string
        Returns:
        a formatted string
        Throws:
        java.text.ParseException - if the syntax of the choice format is wrong

      • formatChoice

        public static java.lang.String formatChoice​(java.lang.String message,
                                            long reference)
                                     throws java.text.ParseException
        Static convenience method to format choices without an IString instance.
        Parameters:
        message - string to format
        reference - reference value
        Returns:
        a formatted string
        Throws:
        java.text.ParseException - if the syntax of the choice format is wrong

      • format

        public static java.lang.String format​(java.lang.String message,
                                      java.util.HashMap<java.lang.String,​java.lang.String> parameters)
        Static convenience method to format without an IString instance.
        Parameters:
        message - string to format
        parameters - parameters to format into the string
        Returns:
        a formatted string

      • formatChoice

        public static java.lang.String formatChoice​(java.lang.String message,
                                            double reference)
                                     throws java.text.ParseException
        Static convenience method to format choices without an IString instance.
        Parameters:
        message - string to format
        reference - reference value
        Returns:
        a formatted string
        Throws:
        java.text.ParseException - if the syntax of the choice format is wrong