Package com.squareup.phrase

Class Phrase

java.lang.Object

com.squareup.phrase.Phrase

public final class Phrase
extends Object

A fluent API for formatting Strings. Canonical usage:

   CharSequence formatted = Phrase.from("Hi {first_name}, you are {age} years old.")
       .put("first_name", firstName)
       .put("age", age)
       .format();
 

• Surround keys with curly braces; use two {{ to escape.
• Keys start with lowercase letters followed by lowercase letters and underscores.
• Spans are preserved, such as simple HTML tags found in strings.xml.
• Fails fast on any mismatched keys.

The constructor parses the original pattern into a doubly-linked list of Phrase.Tokens. These tokens do not modify the original pattern, thus preserving any spans.

The format() method iterates over the tokens, replacing text as it iterates. The doubly-linked list allows each token to ask its predecessor for the expanded length.

Method Summary

Modifier and Type	Method	Description
CharSequence	format()	Returns the text after replacing all keys with values.
static Phrase	from(Fragment f, int patternResourceId)	Entry point into this API.
static Phrase	from(Context c, int patternResourceId)	Entry point into this API.
static Phrase	from(Resources r, int patternResourceId)	Entry point into this API.
static Phrase	from(View v, int patternResourceId)	Entry point into this API.
static Phrase	from(CharSequence pattern)	Entry point into this API; pattern must be non-null.
static Phrase	fromPlural(Context c, int patternResourceId, int quantity)	Entry point into this API.
static Phrase	fromPlural(Resources r, int patternResourceId, int quantity)	Entry point into this API.
static Phrase	fromPlural(View v, int patternResourceId, int quantity)	Entry point into this API.
void	into(TextView textView)	"Formats and sets as text in textView."
Phrase	put(String key, int value)	Replaces the given key with the Integer.toString(int) value for the given int.
Phrase	put(String key, CharSequence value)	Replaces the given key with a non-null value.
Phrase	putOptional(String key, int value)	Replaces the given key, if it exists, with the Integer.toString(int) value for the given int.
Phrase	putOptional(String key, CharSequence value)	Silently ignored if the key is not in the pattern.
String	toString()	Returns the raw pattern without expanding keys; only useful for debugging.

Methods inherited from class java.lang.Object

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

Method Detail

from

public static Phrase from(Fragment f,
                          @StringRes
                          int patternResourceId)

Entry point into this API.

Throws:

IllegalArgumentException - if pattern contains any syntax errors.

from

public static Phrase from(View v,
                          @StringRes
                          int patternResourceId)

Entry point into this API.

Throws:

IllegalArgumentException - if pattern contains any syntax errors.

from

public static Phrase from(Context c,
                          @StringRes
                          int patternResourceId)

Entry point into this API.

Throws:

IllegalArgumentException - if pattern contains any syntax errors.

from

public static Phrase from(Resources r,
                          @StringRes
                          int patternResourceId)

Entry point into this API.

Throws:

IllegalArgumentException - if pattern contains any syntax errors.

fromPlural

public static Phrase fromPlural(View v,
                                @PluralsRes
                                int patternResourceId,
                                int quantity)

Entry point into this API.

Throws:

IllegalArgumentException - if pattern contains any syntax errors.

fromPlural

public static Phrase fromPlural(Context c,
                                @PluralsRes
                                int patternResourceId,
                                int quantity)

Entry point into this API.

Throws:

IllegalArgumentException - if pattern contains any syntax errors.

fromPlural

public static Phrase fromPlural(Resources r,
                                @PluralsRes
                                int patternResourceId,
                                int quantity)

Entry point into this API.

Throws:

IllegalArgumentException - if pattern contains any syntax errors.

from

public static Phrase from(CharSequence pattern)

Entry point into this API; pattern must be non-null.

Throws:

IllegalArgumentException - if pattern contains any syntax errors.

put

public Phrase put(String key,
                  CharSequence value)

Replaces the given key with a non-null value. You may reuse Phrase instances and replace keys with new values.

Throws:

IllegalArgumentException - if the key is not in the pattern.

put

public Phrase put(String key,
                  int value)

Replaces the given key with the Integer.toString(int) value for the given int.

See Also:

put(String, CharSequence)

putOptional

public Phrase putOptional(String key,
                          CharSequence value)

Silently ignored if the key is not in the pattern.

See Also:

put(String, CharSequence)

putOptional

public Phrase putOptional(String key,
                          int value)

Replaces the given key, if it exists, with the Integer.toString(int) value for the given int.

See Also:

putOptional(String, CharSequence)

format

public CharSequence format()

Returns the text after replacing all keys with values.

Throws:

IllegalArgumentException - if any keys are not replaced.

into

public void into(TextView textView)

"Formats and sets as text in textView."

toString

public String toString()

Returns the raw pattern without expanding keys; only useful for debugging. Does not pass through to format() because doing so would drop all spans.

Overrides:

toString in class Object