text/style/TtsSpan.java

/*
 * Copyright (C) 2014 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package android.text.style;

import java.text.NumberFormat;
import java.util.Locale;

import android.os.Parcel;
import android.os.PersistableBundle;
import android.text.ParcelableSpan;
import android.text.TextUtils;

/**
 * A span that supplies additional meta-data for the associated text intended
 * for text-to-speech engines. If the text is being processed by a
 * text-to-speech engine, the engine may use the data in this span in addition
 * to or instead of its associated text.
 *
 * Each instance of a TtsSpan has a type, for example {@link #TYPE_DATE}
 * or {@link #TYPE_MEASURE}. And a list of arguments, provided as
 * key-value pairs in a bundle.
 *
 * The inner classes are there for convenience and provide builders for each
 * TtsSpan type.
 */
public class TtsSpan implements ParcelableSpan {
    private final String mType;
    private final PersistableBundle mArgs;

    /**
     * This span type can be used to add morphosyntactic features to the text it
     * spans over, or synthesize a something else than the spanned text. Use
     * the argument {@link #ARG_TEXT} to set a different text.
     * Accepts the arguments {@link #ARG_GENDER},
     * {@link #ARG_ANIMACY}, {@link #ARG_MULTIPLICITY} and
     * {@link #ARG_CASE}.
     */
    public static final String TYPE_TEXT = "android.type.text";

    /**
     * The text associated with this span is a cardinal. Must include the
     * number to be synthesized with {@link #ARG_NUMBER}.
     * Also accepts the arguments {@link #ARG_GENDER},
     * {@link #ARG_ANIMACY}, {@link #ARG_MULTIPLICITY} and
     * {@link #ARG_CASE}.
     */
    public static final String TYPE_CARDINAL = "android.type.cardinal";

    /**
     * The text associated with this span is an ordinal. Must include the
     * number to be synthesized with {@link #ARG_NUMBER}.
     * Also accepts the arguments {@link #ARG_GENDER},
     * {@link #ARG_ANIMACY}, {@link #ARG_MULTIPLICITY} and
     * {@link #ARG_CASE}.
     */
    public static final String TYPE_ORDINAL = "android.type.ordinal";

    /**
     * The text associated with this span is a decimal number. Must include the
     * number to be synthesized with {@link #ARG_INTEGER_PART} and
     * {@link #ARG_FRACTIONAL_PART}.
     * Also accepts the arguments {@link #ARG_GENDER},
     * {@link #ARG_ANIMACY}, {@link #ARG_MULTIPLICITY} and
     * {@link #ARG_CASE}.
     */
    public static final String TYPE_DECIMAL = "android.type.decimal";

    /**
     * The text associated with this span is a fractional number. Must include
     * the number to be synthesized with {@link #ARG_NUMERATOR} and
     * {@link #ARG_DENOMINATOR}. {@link #ARG_INTEGER_PART} is optional
     * Also accepts the arguments {@link #ARG_GENDER},
     * {@link #ARG_ANIMACY}, {@link #ARG_MULTIPLICITY} and
     * {@link #ARG_CASE}.
     */
    public static final String TYPE_FRACTION = "android.type.fraction";

    /**
     * The text associated with this span is a measure, consisting of a number
     * and a unit. The number can be a cardinal, decimal or a fraction. Set the
     * number with the same arguments as {@link #TYPE_CARDINAL},
     * {@link #TYPE_DECIMAL} or {@link #TYPE_FRACTION}. The unit can be
     * specified with {@link #ARG_UNIT}.
     * Also accepts the arguments {@link #ARG_GENDER},
     * {@link #ARG_ANIMACY}, {@link #ARG_MULTIPLICITY} and
     * {@link #ARG_CASE}.
     */
    public static final String TYPE_MEASURE = "android.type.measure";

    /**
     * The text associated with this span is a time, consisting of a number of
     * hours and minutes, specified with {@link #ARG_HOURS} and
     * {@link #ARG_MINUTES}.
     * Also accepts the arguments {@link #ARG_GENDER},
     * {@link #ARG_ANIMACY}, {@link #ARG_MULTIPLICITY} and
     * {@link #ARG_CASE}.
     */
    public static final String TYPE_TIME = "android.type.time";

    /**
     * The text associated with this span is a date. At least one of the
     * arguments {@link #ARG_MONTH} and {@link #ARG_YEAR} has to be provided.
     * The argument {@link #ARG_DAY} is optional if {@link #ARG_MONTH} is set.
     * The argument {@link #ARG_WEEKDAY} is optional if {@link #ARG_DAY} is set.
     * Also accepts the arguments {@link #ARG_GENDER}, {@link #ARG_ANIMACY},
     * {@link #ARG_MULTIPLICITY} and {@link #ARG_CASE}.
     */
    public static final String TYPE_DATE = "android.type.date";

    /**
     * The text associated with this span is a telephone number. The argument
     * {@link #ARG_NUMBER_PARTS} is required. {@link #ARG_COUNTRY_CODE} and
     * {@link #ARG_EXTENSION} are optional.
     * Also accepts the arguments {@link #ARG_GENDER}, {@link #ARG_ANIMACY},
     * {@link #ARG_MULTIPLICITY} and {@link #ARG_CASE}.
     */
    public static final String TYPE_TELEPHONE = "android.type.telephone";

    /**
     * The text associated with this span is a URI (can be used for URLs and
     * email addresses). The full schema for URLs, which email addresses can
     * effectively be seen as a subset of, is:
     * protocol://username:password@domain:port/path?query_string#fragment_id
     * Hence populating just username and domain will read as an email address.
     * All arguments are optional, but at least one has to be provided:
     * {@link #ARG_PROTOCOL}, {@link #ARG_USERNAME}, {@link #ARG_PASSWORD},
     * {@link #ARG_DOMAIN}, {@link #ARG_PORT}, {@link #ARG_PATH},
     * {@link #ARG_QUERY_STRING} and {@link #ARG_FRAGMENT_ID}.
     * Also accepts the arguments {@link #ARG_GENDER}, {@link #ARG_ANIMACY},
     * {@link #ARG_MULTIPLICITY} and {@link #ARG_CASE}.
     */
    public static final String TYPE_ELECTRONIC = "android.type.electronic";

    /**
     * The text associated with this span is an amount of money. Set the amount
     * with the same arguments as {@link #TYPE_DECIMAL}.
     * {@link #ARG_CURRENCY} is used to set the currency. {@link #ARG_QUANTITY}
     * is optional.
     * Also accepts the arguments {@link #ARG_GENDER}, {@link #ARG_ANIMACY},
     * {@link #ARG_MULTIPLICITY} and {@link #ARG_CASE}.
     */
    public static final String TYPE_MONEY = "android.type.money";

    /**
     * The text associated with this span is a series of digits that have to be
     * read sequentially. The digits can be set with {@link #ARG_DIGITS}.
     * Also accepts the arguments {@link #ARG_GENDER}, {@link #ARG_ANIMACY},
     * {@link #ARG_MULTIPLICITY} and {@link #ARG_CASE}.
     */
    public static final String TYPE_DIGITS = "android.type.digits";

    /**
     * The text associated with this span is a series of characters that have to
     * be read verbatim. The engine will attempt to ready out any character like
     * punctuation but excluding whitespace. {@link #ARG_VERBATIM} is required.
     * Also accepts the arguments {@link #ARG_GENDER},
     * {@link #ARG_ANIMACY}, {@link #ARG_MULTIPLICITY} and {@link #ARG_CASE}.
     */
    public static final String TYPE_VERBATIM = "android.type.verbatim";

    /**
     * String argument supplying gender information. Can be any of
     * {@link #GENDER_NEUTRAL}, {@link #GENDER_MALE} and
     * {@link #GENDER_FEMALE}.
     */
    public static final String ARG_GENDER = "android.arg.gender";

    public static final String GENDER_NEUTRAL = "android.neutral";
    public static final String GENDER_MALE = "android.male";
    public static final String GENDER_FEMALE = "android.female";

    /**
     * String argument supplying animacy information. Can be
     * {@link #ANIMACY_ANIMATE} or
     * {@link #ANIMACY_INANIMATE}
     */
    public static final String ARG_ANIMACY = "android.arg.animacy";

    public static final String ANIMACY_ANIMATE = "android.animate";
    public static final String ANIMACY_INANIMATE = "android.inanimate";

    /**
     * String argument supplying multiplicity information. Can be any of
     * {@link #MULTIPLICITY_SINGLE}, {@link #MULTIPLICITY_DUAL} and
     * {@link #MULTIPLICITY_PLURAL}
     */
    public static final String ARG_MULTIPLICITY = "android.arg.multiplicity";

    public static final String MULTIPLICITY_SINGLE = "android.single";
    public static final String MULTIPLICITY_DUAL = "android.dual";
    public static final String MULTIPLICITY_PLURAL = "android.plural";

    /**
     * String argument supplying case information. Can be any of
     * {@link #CASE_NOMINATIVE}, {@link #CASE_ACCUSATIVE}, {@link #CASE_DATIVE},
     * {@link #CASE_ABLATIVE}, {@link #CASE_GENITIVE}, {@link #CASE_VOCATIVE},
     * {@link #CASE_LOCATIVE} and {@link #CASE_INSTRUMENTAL}
     */
    public static final String ARG_CASE = "android.arg.case";

    public static final String CASE_NOMINATIVE = "android.nominative";
    public static final String CASE_ACCUSATIVE = "android.accusative";
    public static final String CASE_DATIVE = "android.dative";
    public static final String CASE_ABLATIVE = "android.ablative";
    public static final String CASE_GENITIVE = "android.genitive";
    public static final String CASE_VOCATIVE = "android.vocative";
    public static final String CASE_LOCATIVE = "android.locative";
    public static final String CASE_INSTRUMENTAL = "android.instrumental";

    /**
     * String supplying the text to be synthesized. The synthesizer is free
     * to decide how to interpret the text.
     * Can be used with {@link #TYPE_TEXT}.
     */
    public static final String ARG_TEXT = "android.arg.text";

    /**
     * Argument used to specify a whole number. The value can be a string of
     * digits of any size optionally prefixed with a - or +.
     * Can be used with {@link #TYPE_CARDINAL} and {@link #TYPE_ORDINAL}.
     */
    public static final String ARG_NUMBER = "android.arg.number";

    /**
     * Argument used to specify the integer part of a decimal or fraction. The
     * value can be a string of digits of any size optionally prefixed with
     * a - or +.
     * Can be used with {@link #TYPE_DECIMAL} and {@link #TYPE_FRACTION}.
     */
    public static final String ARG_INTEGER_PART = "android.arg.integer_part";

    /**
     * Argument used to specify the fractional part of a decimal. The value can
     * be a string of digits of any size.
     * Can be used with {@link #TYPE_DECIMAL}.
     */
    public static final String ARG_FRACTIONAL_PART =
        "android.arg.fractional_part";

    /**
     * Argument used to choose the suffix (thousand, million, etc) that is used
     * to pronounce large amounts of money. For example it can be used to
     * disambiguate between "two thousand five hundred dollars" and
     * "two point five thousand dollars".
     * If implemented, engines should support at least "1000", "1000000",
     * "1000000000" and "1000000000000".
     * Example: if the {@link #ARG_INTEGER_PART} argument is "10", the
     * {@link #ARG_FRACTIONAL_PART} argument is "4", the {@link #ARG_QUANTITY}
     * argument is "1000" and the {@link #ARG_CURRENCY} argument is "usd", the
     * TTS engine may pronounce the span as "ten point four thousand dollars".
     * With the same example but with the quantity set as "1000000" the TTS
     * engine may pronounce the span as "ten point four million dollars".
     * Can be used with {@link #TYPE_MONEY}.
     */
    public static final String ARG_QUANTITY =
            "android.arg.quantity";

    /**
     * Argument used to specify the numerator of a fraction. The value can be a
     * string of digits of any size optionally prefixed with a - or +.
     * Can be used with {@link #TYPE_FRACTION}.
     */
    public static final String ARG_NUMERATOR = "android.arg.numerator";

    /**
     * Argument used to specify the denominator of a fraction. The value can be
     * a string of digits of any size optionally prefixed with a + or -.
     * Can be used with {@link #TYPE_FRACTION}.
     */
    public static final String ARG_DENOMINATOR = "android.arg.denominator";

    /**
     * Argument used to specify the unit of a measure. The unit should always be
     * specified in English singular form. Prefixes may be used. Engines will do
     * their best to pronounce them correctly in the language used. Engines are
     * expected to at least support the most common ones like "meter", "second",
     * "degree celsius" and "degree fahrenheit" with some common prefixes like
     * "milli" and "kilo".
     * Can be used with {@link #TYPE_MEASURE}.
     */
    public static final String ARG_UNIT = "android.arg.unit";

    /**
     * Argument used to specify the hours of a time. The hours should be
     * provided as an integer in the range from 0 up to and including 24.
     * Can be used with {@link #TYPE_TIME}.
     */
    public static final String ARG_HOURS = "android.arg.hours";

    /**
     * Argument used to specify the minutes of a time. The hours should be
     * provided as an integer in the range from 0 up to and including 59.
     * Can be used with {@link #TYPE_TIME}.
     */
    public static final String ARG_MINUTES = "android.arg.minutes";

    /**
     * Argument used to specify the weekday of a date. The value should be
     * provided as an integer and can be any of {@link #WEEKDAY_SUNDAY},
     * {@link #WEEKDAY_MONDAY}, {@link #WEEKDAY_TUESDAY},
     * {@link #WEEKDAY_WEDNESDAY}, {@link #WEEKDAY_THURSDAY},
     * {@link #WEEKDAY_FRIDAY} and {@link #WEEKDAY_SATURDAY}.
     * Can be used with {@link #TYPE_DATE}.
     */
    public static final String ARG_WEEKDAY = "android.arg.weekday";

    public static final int WEEKDAY_SUNDAY = 1;
    public static final int WEEKDAY_MONDAY = 2;
    public static final int WEEKDAY_TUESDAY = 3;
    public static final int WEEKDAY_WEDNESDAY = 4;
    public static final int WEEKDAY_THURSDAY = 5;
    public static final int WEEKDAY_FRIDAY = 6;
    public static final int WEEKDAY_SATURDAY = 7;

    /**
     * Argument used to specify the day of the month of a date. The value should
     * be provided as an integer in the range from 1 up to and including 31.
     * Can be used with {@link #TYPE_DATE}.
     */
    public static final String ARG_DAY = "android.arg.day";

    /**
     * Argument used to specify the month of a date. The value should be
     * provided as an integer and can be any of {@link #MONTH_JANUARY},
     * {@link #MONTH_FEBRUARY},  {@link #MONTH_MARCH}, {@link #MONTH_APRIL},
     * {@link #MONTH_MAY}, {@link #MONTH_JUNE}, {@link #MONTH_JULY},
     * {@link #MONTH_AUGUST}, {@link #MONTH_SEPTEMBER}, {@link #MONTH_OCTOBER},
     * {@link #MONTH_NOVEMBER} and {@link #MONTH_DECEMBER}.
     * Can be used with {@link #TYPE_DATE}.
     */
    public static final String ARG_MONTH = "android.arg.month";

    public static final int MONTH_JANUARY = 0;
    public static final int MONTH_FEBRUARY = 1;
    public static final int MONTH_MARCH = 2;
    public static final int MONTH_APRIL = 3;
    public static final int MONTH_MAY = 4;
    public static final int MONTH_JUNE = 5;
    public static final int MONTH_JULY = 6;
    public static final int MONTH_AUGUST = 7;
    public static final int MONTH_SEPTEMBER = 8;
    public static final int MONTH_OCTOBER = 9;
    public static final int MONTH_NOVEMBER = 10;
    public static final int MONTH_DECEMBER = 11;

    /**
     * Argument used to specify the year of a date. The value should be provided
     * as a positive integer.
     * Can be used with {@link #TYPE_DATE}.
     */
    public static final String ARG_YEAR = "android.arg.year";

    /**
     * Argument used to specify the country code of a telephone number. Can be
     * a string of digits optionally prefixed with a "+".
     * Can be used with {@link #TYPE_TELEPHONE}.
     */
    public static final String ARG_COUNTRY_CODE = "android.arg.country_code";

    /**
     * Argument used to specify the main number part of a telephone number. Can
     * be a string of digits where the different parts of the telephone number
     * can be separated with a space, '-', '/' or '.'.
     * Can be used with {@link #TYPE_TELEPHONE}.
     */
    public static final String ARG_NUMBER_PARTS = "android.arg.number_parts";

    /**
     * Argument used to specify the extension part of a telephone number. Can be
     * a string of digits.
     * Can be used with {@link #TYPE_TELEPHONE}.
     */
    public static final String ARG_EXTENSION = "android.arg.extension";

    /**
     * Argument used to specify the protocol of a URI. Examples are "http" and
     * "ftp".
     * Can be used with {@link #TYPE_ELECTRONIC}.
     */
    public static final String ARG_PROTOCOL = "android.arg.protocol";

    /**
     * Argument used to specify the username part of a URI. Should be set as a
     * string.
     * Can be used with {@link #TYPE_ELECTRONIC}.
     */
    public static final String ARG_USERNAME = "android.arg.username";

    /**
     * Argument used to specify the password part of a URI. Should be set as a
     * string.
     * Can be used with {@link #TYPE_ELECTRONIC}.
     */
    public static final String ARG_PASSWORD = "android.arg.password";

    /**
     * Argument used to specify the domain part of a URI. For example
     * "source.android.com".
     * Can be used with {@link #TYPE_ELECTRONIC}.
     */
    public static final String ARG_DOMAIN = "android.arg.domain";

    /**
     * Argument used to specify the port number of a URI. Should be specified as
     * an integer.
     * Can be used with {@link #TYPE_ELECTRONIC}.
     */
    public static final String ARG_PORT = "android.arg.port";

    /**
     * Argument used to specify the path part of a URI. For example
     * "source/index.html".
     * Can be used with {@link #TYPE_ELECTRONIC}.
     */
    public static final String ARG_PATH = "android.arg.path";

    /**
     * Argument used to specify the query string of a URI. For example
     * "arg=value&argtwo=value".
     * Can be used with {@link #TYPE_ELECTRONIC}.
     */
    public static final String ARG_QUERY_STRING = "android.arg.query_string";

    /**
     * Argument used to specify the fragment id of a URI. Should be specified as
     * a string.
     * Can be used with {@link #TYPE_ELECTRONIC}.
     */
    public static final String ARG_FRAGMENT_ID = "android.arg.fragment_id";

    /**
     * Argument used to specify the currency. Should be a ISO4217 currency code,
     * e.g. "USD".
     * Can be used with {@link #TYPE_MONEY}.
     */
    public static final String ARG_CURRENCY = "android.arg.money";

    /**
     * Argument used to specify a string of digits.
     * Can be used with {@link #TYPE_DIGITS}.
     */
    public static final String ARG_DIGITS = "android.arg.digits";

    /**
     * Argument used to specify a string where the characters are read verbatim,
     * except whitespace.
     * Can be used with {@link #TYPE_VERBATIM}.
     */
    public static final String ARG_VERBATIM = "android.arg.verbatim";

    public TtsSpan(String type, PersistableBundle args) {
        mType = type;
        mArgs = args;
    }

    public TtsSpan(Parcel src) {
        mType = src.readString();
        mArgs = src.readPersistableBundle();
    }

    /**
     * Returns the type.
     * @return The type of this instance.
     */
    public String getType() {
        return mType;
    }

    /**
     * Returns a bundle of the arguments set.
     * @return The bundle of the arguments set.
     */
    public PersistableBundle getArgs() {
        return mArgs;
    }

    @Override
    public int describeContents() {
        return 0;
    }

    @Override
    public void writeToParcel(Parcel dest, int flags) {
        dest.writeString(mType);
        dest.writePersistableBundle(mArgs);
    }

    @Override
    public int getSpanTypeId() {
        return TextUtils.TTS_SPAN;
    }

    /**
     * A simple builder for TtsSpans.
     * This builder can be used directly, but the more specific subclasses of
     * this builder like {@link TtsSpan.TextBuilder} and
     * {@link TtsSpan.CardinalBuilder} are likely more useful.
     *
     * This class uses generics so methods from this class can return instances
     * of its child classes, resulting in a fluent API (CRTP pattern).
     */
    public static class Builder<C extends Builder<?>> {
        // Holds the type of this class.
        private final String mType;

        // Holds the arguments of this class. It only stores objects of type
        // String, Integer and Long.
        private PersistableBundle mArgs = new PersistableBundle();

        public Builder(String type) {
            mType = type;
        }

        /**
         * Returns a TtsSpan built from the parameters set by the setter
         * methods.
         * @return A TtsSpan built with parameters of this builder.
         */
        public TtsSpan build() {
            return new TtsSpan(mType, mArgs);
        }

        /**
         * Sets an argument to a string value.
         * @param arg The argument name.
         * @param value The value the argument should be set to.
         * @return This instance.
         */
        @SuppressWarnings("unchecked")
        public C setStringArgument(String arg, String value) {
            mArgs.putString(arg, value);
            return (C) this;
        }

        /**
         * Sets an argument to an int value.
         * @param arg The argument name.
         * @param value The value the argument should be set to.
         */
        @SuppressWarnings("unchecked")
        public C setIntArgument(String arg, int value) {
            mArgs.putInt(arg, value);
            return (C) this;
        }

        /**
         * Sets an argument to a long value.
         * @param arg The argument name.
         * @param value The value the argument should be set to.
         */
        @SuppressWarnings("unchecked")
        public C setLongArgument(String arg, long value) {
            mArgs.putLong(arg, value);
            return (C) this;
        }
    }

    /**
     * A builder for TtsSpans, has setters for morphosyntactic features.
     * This builder can be used directly, but the more specific subclasses of
     * this builder like {@link TtsSpan.TextBuilder} and
     * {@link TtsSpan.CardinalBuilder} are likely more useful.
     */
    public static class SemioticClassBuilder<C extends SemioticClassBuilder<?>>
            extends Builder<C> {

        public SemioticClassBuilder(String type) {
            super(type);
        }

        /**
         * Sets the gender information for this instance.
         * @param gender Can any of {@link #GENDER_NEUTRAL},
         *     {@link #GENDER_MALE} and {@link #GENDER_FEMALE}.
         * @return This instance.
         */
        public C setGender(String gender) {
            return setStringArgument(TtsSpan.ARG_GENDER, gender);
        }

        /**
         * Sets the animacy information for this instance.
         * @param animacy Can be any of {@link #ANIMACY_ANIMATE} and
         *     {@link #ANIMACY_INANIMATE}.
         * @return This instance.
         */
        public C setAnimacy(String animacy) {
            return setStringArgument(TtsSpan.ARG_ANIMACY, animacy);
        }

        /**
         * Sets the multiplicity information for this instance.
         * @param multiplicity Can be any of
         *     {@link #MULTIPLICITY_SINGLE}, {@link #MULTIPLICITY_DUAL} and
         *     {@link #MULTIPLICITY_PLURAL}.
         * @return This instance.
         */
        public C setMultiplicity(String multiplicity) {
            return setStringArgument(TtsSpan.ARG_MULTIPLICITY, multiplicity);
        }

        /**
         * Sets the grammatical case information for this instance.
         * @param grammaticalCase Can be any of {@link #CASE_NOMINATIVE},
         *     {@link #CASE_ACCUSATIVE}, {@link #CASE_DATIVE},
         *     {@link #CASE_ABLATIVE}, {@link #CASE_GENITIVE},
         *     {@link #CASE_VOCATIVE}, {@link #CASE_LOCATIVE} and
         *     {@link #CASE_INSTRUMENTAL}.
         * @return This instance.
         */
        public C setCase(String grammaticalCase) {
            return setStringArgument(TtsSpan.ARG_CASE, grammaticalCase);
        }
    }

    /**
     * A builder for TtsSpans of type {@link #TYPE_TEXT}.
     */
    public static class TextBuilder extends SemioticClassBuilder<TextBuilder> {

        /**
         * Creates a builder for a TtsSpan of type {@link #TYPE_TEXT}.
         */
        public TextBuilder() {
            super(TtsSpan.TYPE_TEXT);
        }

        /**
         * Creates a TtsSpan of type {@link #TYPE_TEXT} and sets the
         * {@link #ARG_TEXT} argument.
         * @param text The text to be synthesized.
         * @see #setText(String)
         */
        public TextBuilder(String text) {
            this();
            setText(text);
        }

        /**
         * Sets the {@link #ARG_TEXT} argument, the text to be synthesized.
         * @param text The string that will be synthesized.
         * @return This instance.
         */
        public TextBuilder setText(String text) {
            return setStringArgument(TtsSpan.ARG_TEXT, text);
        }
    }

    /**
     * A builder for TtsSpans of type {@link #TYPE_CARDINAL}.
     */
    public static class CardinalBuilder
            extends SemioticClassBuilder<CardinalBuilder> {

        /**
         * Creates a builder for a TtsSpan of type {@link #TYPE_CARDINAL}.
         */
        public CardinalBuilder() {
            super(TtsSpan.TYPE_CARDINAL);
        }

        /**
         * Creates a TtsSpan of type {@link #TYPE_CARDINAL} and sets the
         * {@link #ARG_NUMBER} argument.
         * @param number The number to synthesize.
         * @see #setNumber(long)
         */
        public CardinalBuilder(long number) {
            this();
            setNumber(number);
        }

        /**
         * Creates a TtsSpan of type {@link #TYPE_CARDINAL} and sets the
         * {@link #ARG_NUMBER} argument.
         * @param number The number to synthesize.
         * @see #setNumber(String)
         */
        public CardinalBuilder(String number) {
            this();
            setNumber(number);
        }

        /**
         * Convenience method that converts the number to a String and set it to
         * the value for {@link #ARG_NUMBER}.
         * @param number The number that will be synthesized.
         * @return This instance.
         */
        public CardinalBuilder setNumber(long number) {
            return setNumber(String.valueOf(number));
        }

        /**
         * Sets the {@link #ARG_NUMBER} argument.
         * @param number A non-empty string of digits with an optional
         *     leading + or -.
         * @return This instance.
         */
        public CardinalBuilder setNumber(String number) {
            return setStringArgument(TtsSpan.ARG_NUMBER, number);
        }
    }

    /**
     * A builder for TtsSpans of type {@link #TYPE_ORDINAL}.
     */
    public static class OrdinalBuilder
            extends SemioticClassBuilder<OrdinalBuilder> {

        /**
         * Creates a builder for a TtsSpan of type {@link #TYPE_ORDINAL}.
         */
        public OrdinalBuilder() {
            super(TtsSpan.TYPE_ORDINAL);
        }

        /**
         * Creates a TtsSpan of type {@link #TYPE_ORDINAL} and sets the
         * {@link #ARG_NUMBER} argument.
         * @param number The ordinal number to synthesize.
         * @see #setNumber(long)
         */
        public OrdinalBuilder(long number) {
            this();
            setNumber(number);
        }

        /**
         * Creates a TtsSpan of type {@link #TYPE_ORDINAL} and sets the
         * {@link #ARG_NUMBER} argument.
         * @param number The number to synthesize.
         * @see #setNumber(String)
         */
        public OrdinalBuilder(String number) {
            this();
            setNumber(number);
        }

        /**
         * Convenience method that converts the number to a String and sets it
         * to the value for {@link #ARG_NUMBER}.
         * @param number The ordinal number that will be synthesized.
         * @return This instance.
         */
        public OrdinalBuilder setNumber(long number) {
            return setNumber(String.valueOf(number));
        }

        /**
         * Sets the {@link #ARG_NUMBER} argument.
         * @param number A non-empty string of digits with an optional
         *     leading + or -.
         * @return This instance.
         */
        public OrdinalBuilder setNumber(String number) {
            return setStringArgument(TtsSpan.ARG_NUMBER, number);
        }
    }

    /**
     * A builder for TtsSpans of type {@link #TYPE_DECIMAL}.
     */
    public static class DecimalBuilder
            extends SemioticClassBuilder<DecimalBuilder> {

        /**
         * Creates a builder for a TtsSpan of type {@link #TYPE_DECIMAL}.
         */
        public DecimalBuilder() {
            super(TtsSpan.TYPE_DECIMAL);
        }

        /**
         * Creates a TtsSpan of type {@link #TYPE_DECIMAL} and sets the
         * {@link #ARG_INTEGER_PART} and {@link #ARG_FRACTIONAL_PART} arguments.
         * @see {@link #setArgumentsFromDouble(double, int, int)
         */
        public DecimalBuilder(double number,
                              int minimumFractionDigits,
                              int maximumFractionDigits) {
            this();
            setArgumentsFromDouble(number,
                                   minimumFractionDigits,
                                   maximumFractionDigits);
        }

        /**
         * Creates a TtsSpan of type {@link #TYPE_DECIMAL} and sets the
         * {@link #ARG_INTEGER_PART} and {@link #ARG_FRACTIONAL_PART} arguments.
         */
        public DecimalBuilder(String integerPart, String fractionalPart) {
            this();
            setIntegerPart(integerPart);
            setFractionalPart(fractionalPart);
        }

        /**
         * Convenience method takes a double and a maximum number of fractional
         * digits, it sets the {@link #ARG_INTEGER_PART} and
         * {@link #ARG_FRACTIONAL_PART} arguments.
         * @param number The number to be synthesized.
         * @param minimumFractionDigits The minimum number of fraction digits
         *     that are pronounced.
         * @param maximumFractionDigits The maximum number of fraction digits
         *     that are pronounced. If maximumFractionDigits <
         *     minimumFractionDigits then minimumFractionDigits will be assumed
         *     to be equal to maximumFractionDigits.
         * @return This instance.
         */
        public DecimalBuilder setArgumentsFromDouble(
                double number,
                int minimumFractionDigits,
                int maximumFractionDigits) {
            // Format double.
            NumberFormat formatter = NumberFormat.getInstance(Locale.US);
            formatter.setMinimumFractionDigits(maximumFractionDigits);
            formatter.setMaximumFractionDigits(maximumFractionDigits);
            formatter.setGroupingUsed(false);
            String str = formatter.format(number);

            // Split at decimal point.
            int i = str.indexOf('.');
            if (i >= 0) {
                setIntegerPart(str.substring(0, i));
                setFractionalPart(str.substring(i + 1));
            } else {
                setIntegerPart(str);
            }
            return this;
        }

        /**
         * Convenience method that converts the number to a String and sets it
         * to the value for {@link #ARG_INTEGER_PART}.
         * @param integerPart The integer part of the decimal.
         * @return This instance.
         */
        public DecimalBuilder setIntegerPart(long integerPart) {
            return setIntegerPart(String.valueOf(integerPart));
        }

        /**
         * Sets the {@link #ARG_INTEGER_PART} argument.
         * @param integerPart A non-empty string of digits with an optional
         *     leading + or -.
         * @return This instance.
         */
        public DecimalBuilder setIntegerPart(String integerPart) {
            return setStringArgument(TtsSpan.ARG_INTEGER_PART, integerPart);
        }

        /**
         * Sets the {@link #ARG_FRACTIONAL_PART} argument.
         * @param fractionalPart A non-empty string of digits.
         * @return This instance.
         */
        public DecimalBuilder setFractionalPart(String fractionalPart) {
            return setStringArgument(TtsSpan.ARG_FRACTIONAL_PART,
                                     fractionalPart);
        }
    }

    /**
     * A builder for TtsSpans of type {@link #TYPE_FRACTION}.
     */
    public static class FractionBuilder
            extends SemioticClassBuilder<FractionBuilder> {

        /**
         * Creates a builder for a TtsSpan of type {@link #TYPE_FRACTION}.
         */
        public FractionBuilder() {
            super(TtsSpan.TYPE_FRACTION);
        }

        /**
         * Creates a TtsSpan of type {@link #TYPE_FRACTION} and sets the
         * {@link #ARG_INTEGER_PART}, {@link #ARG_NUMERATOR}, and
         * {@link #ARG_DENOMINATOR} arguments.
         */
        public FractionBuilder(long integerPart,
                               long numerator,
                               long denominator) {
            this();
            setIntegerPart(integerPart);
            setNumerator(numerator);
            setDenominator(denominator);
        }

        /**
         * Convenience method that converts the integer to a String and sets the
         * argument {@link #ARG_NUMBER}.
         * @param integerPart The integer part.
         * @return This instance.
         */
        public FractionBuilder setIntegerPart(long integerPart) {
            return setIntegerPart(String.valueOf(integerPart));
        }

        /**
         * Sets the {@link #ARG_INTEGER_PART} argument.
         * @param integerPart A non-empty string of digits with an optional
         *     leading + or -.
         * @return This instance.
         */
        public FractionBuilder setIntegerPart(String integerPart) {
            return setStringArgument(TtsSpan.ARG_INTEGER_PART, integerPart);
        }

        /**
         * Convenience method that converts the numerator to a String and sets
         * the argument {@link #ARG_NUMERATOR}.
         * @param numerator The numerator.
         * @return This instance.
         */
        public FractionBuilder setNumerator(long numerator) {
            return setNumerator(String.valueOf(numerator));
        }

        /**
         * Sets the {@link #ARG_NUMERATOR} argument.
         * @param numerator A non-empty string of digits with an optional
         *     leading + or -.
         * @return This instance.
         */
        public FractionBuilder setNumerator(String numerator) {
            return setStringArgument(TtsSpan.ARG_NUMERATOR, numerator);
        }

        /**
         * Convenience method that converts the denominator to a String and sets
         * the argument {@link #ARG_DENOMINATOR}.
         * @param denominator The denominator.
         * @return This instance.
         */
        public FractionBuilder setDenominator(long denominator) {
            return setDenominator(String.valueOf(denominator));
        }

        /**
         * Sets the {@link #ARG_DENOMINATOR} argument.
         * @param denominator A non-empty string of digits with an optional
         *     leading + or -.
         * @return This instance.
         */
        public FractionBuilder setDenominator(String denominator) {
            return setStringArgument(TtsSpan.ARG_DENOMINATOR, denominator);
        }
    }

    /**
     * A builder for TtsSpans of type {@link #TYPE_MEASURE}.
     */
    public static class MeasureBuilder
            extends SemioticClassBuilder<MeasureBuilder> {

        /**
         * Creates a builder for a TtsSpan of type {@link #TYPE_MEASURE}.
         */
        public MeasureBuilder() {
            super(TtsSpan.TYPE_MEASURE);
        }

        /**
         * Convenience method that converts the number to a String and set it to
         * the value for {@link #ARG_NUMBER}.
         * @param number The amount of the measure.
         * @return This instance.
         */
        public MeasureBuilder setNumber(long number) {
            return setNumber(String.valueOf(number));
        }

        /**
         * Sets the {@link #ARG_NUMBER} argument.
         * @param number A non-empty string of digits with an optional
         *     leading + or -.
         * @return This instance.
         */
        public MeasureBuilder setNumber(String number) {
            return setStringArgument(TtsSpan.ARG_NUMBER, number);
        }

        /**
         * Convenience method that converts the integer part to a String and set
         * it to the value for {@link #ARG_INTEGER_PART}.
         * @param integerPart The integer part of a decimal or fraction.
         * @return This instance.
         */
        public MeasureBuilder setIntegerPart(long integerPart) {
            return setNumber(String.valueOf(integerPart));
        }

        /**
         * Sets the {@link #ARG_INTEGER_PART} argument.
         * @param integerPart The integer part of a decimal or fraction; a
         * non-empty string of digits with an optional
         *     leading + or -.
         * @return This instance.
         */
        public MeasureBuilder setIntegerPart(String integerPart) {
            return setStringArgument(TtsSpan.ARG_INTEGER_PART, integerPart);
        }

        /**
         * Sets the {@link #ARG_FRACTIONAL_PART} argument.
         * @param fractionalPart The fractional part of a decimal; a non-empty
         *     string of digits with an optional leading + or -.
         * @return This instance.
         */
        public MeasureBuilder setFractionalPart(String fractionalPart) {
            return setStringArgument(TtsSpan.ARG_FRACTIONAL_PART,
                                     fractionalPart);
        }

        /**
         * Convenience method that converts the numerator to a String and set it
         * to the value for {@link #ARG_NUMERATOR}.
         * @param numerator The numerator of a fraction.
         * @return This instance.
         */
        public MeasureBuilder setNumerator(long numerator) {
            return setNumerator(String.valueOf(numerator));
        }

        /**
         * Sets the {@link #ARG_NUMERATOR} argument.
         * @param numerator The numerator of a fraction; a non-empty string of
         *     digits with an optional leading + or -.
         * @return This instance.
         */
        public MeasureBuilder setNumerator(String numerator) {
            return setStringArgument(TtsSpan.ARG_NUMERATOR, numerator);
        }

        /**
         * Convenience method that converts the denominator to a String and set
         * it to the value for {@link #ARG_DENOMINATOR}.
         * @param denominator The denominator of a fraction.
         * @return This instance.
         */
        public MeasureBuilder setDenominator(long denominator) {
            return setDenominator(String.valueOf(denominator));
        }

        /**
         * Sets the {@link #ARG_DENOMINATOR} argument.
         * @param denominator The denominator of a fraction; a non-empty string
         *     of digits with an optional leading + or -.
         * @return This instance.
         */
        public MeasureBuilder setDenominator(String denominator) {
            return setStringArgument(TtsSpan.ARG_DENOMINATOR, denominator);
        }

        /**
         * Sets the {@link #ARG_UNIT} argument.
         * @param unit The unit of the measure.
         * @return This instance.
         * @see {@link TtsSpan.ARG_UNIT}
         */
        public MeasureBuilder setUnit(String unit) {
            return setStringArgument(TtsSpan.ARG_UNIT, unit);
        }
    }

    /**
     * A builder for TtsSpans of type {@link #TYPE_TIME}.
     */
    public static class TimeBuilder
            extends SemioticClassBuilder<TimeBuilder> {

        /**
         * Creates a builder for a TtsSpan of type {@link #TYPE_TIME}.
         */
        public TimeBuilder() {
            super(TtsSpan.TYPE_TIME);
        }

        /**
         * Creates a builder for a TtsSpan of type {@link #TYPE_TIME} and
         * sets the {@link #ARG_HOURS} and {@link #ARG_MINUTES} arguments.
         */
        public TimeBuilder(int hours, int minutes) {
            this();
            setHours(hours);
            setMinutes(minutes);
        }

        /**
         * Sets the {@link #ARG_HOURS} argument.
         * @param hours The value to be set for hours. See {@link #ARG_HOURS}.
         * @return This instance.
         * @see {@link #ARG_HOURS}
         */
        public TimeBuilder setHours(int hours) {
            return setIntArgument(TtsSpan.ARG_HOURS, hours);
        }

        /**
         * Sets the {@link #ARG_MINUTES} argument.
         * @param minutes The value to be set for minutes. See
         *     {@link #ARG_MINUTES}.
         * @return This instance.
         * @see {@link #ARG_MINUTES}
         */
        public TimeBuilder setMinutes(int minutes) {
            return setIntArgument(TtsSpan.ARG_MINUTES, minutes);
        }
    }

    /**
     * A builder for TtsSpans of type {@link #TYPE_DATE}.
     */
    public static class DateBuilder
            extends SemioticClassBuilder<DateBuilder> {

        /**
         * Creates a builder for a TtsSpan of type {@link #TYPE_DATE}.
         */
        public DateBuilder() {
            super(TtsSpan.TYPE_DATE);
        }

        /**
         * Creates a builder for a TtsSpan of type {@link #TYPE_TIME} and
         * possibly sets the {@link #ARG_WEEKDAY}, {@link #ARG_DAY},
         * {@link #ARG_MONTH} and {@link #ARG_YEAR} arguments. Pass null to any
         * argument to leave it unset.
         */
        public DateBuilder(Integer weekday,
                           Integer day,
                           Integer month,
                           Integer year) {
            this();
            if (weekday != null) {
                setWeekday(weekday);
            }
            if (day != null) {
                setDay(day);
            }
            if (month != null) {
                setMonth(month);
            }
            if (year != null) {
                setYear(year);
            }
        }

        /**
         * Sets the {@link #ARG_WEEKDAY} argument.
         * @param weekday The value to be set for weekday. See
         *     {@link #ARG_WEEKDAY}.
         * @return This instance.
         * @see {@link #ARG_WEEKDAY}
         */
        public DateBuilder setWeekday(int weekday) {
            return setIntArgument(TtsSpan.ARG_WEEKDAY, weekday);
        }

        /**
         * Sets the {@link #ARG_DAY} argument.
         * @param day The value to be set for day. See {@link #ARG_DAY}.
         * @return This instance.
         * @see {@link #ARG_DAY}
         */
        public DateBuilder setDay(int day) {
            return setIntArgument(TtsSpan.ARG_DAY, day);
        }

        /**
         * Sets the {@link #ARG_MONTH} argument.
         * @param month The value to be set for month. See {@link #ARG_MONTH}.
         * @return This instance.
         * @see {@link #ARG_MONTH}
         */
        public DateBuilder setMonth(int month) {
            return setIntArgument(TtsSpan.ARG_MONTH, month);
        }

        /**
         * Sets the {@link #ARG_YEAR} argument.
         * @param year The value to be set for year. See {@link #ARG_YEAR}.
         * @return This instance.
         * @see {@link #ARG_YEAR}
         */
        public DateBuilder setYear(int year) {
            return setIntArgument(TtsSpan.ARG_YEAR, year);
        }
    }

    /**
     * A builder for TtsSpans of type {@link #TYPE_MONEY}.
     */
    public static class MoneyBuilder
            extends SemioticClassBuilder<MoneyBuilder> {

        /**
         * Creates a TtsSpan of type {@link #TYPE_MONEY}.
         */
        public MoneyBuilder() {
            super(TtsSpan.TYPE_MONEY);
        }

        /**
         * Convenience method that converts the number to a String and set it to
         * the value for {@link #ARG_INTEGER_PART}.
         * @param integerPart The integer part of the amount.
         * @return This instance.
         */
        public MoneyBuilder setIntegerPart(long integerPart) {
            return setIntegerPart(String.valueOf(integerPart));
        }

        /**
         * Sets the {@link #ARG_INTEGER_PART} argument.
         * @param integerPart A non-empty string of digits with an optional
         *     leading + or -.
         * @return This instance.
         */
        public MoneyBuilder setIntegerPart(String integerPart) {
            return setStringArgument(TtsSpan.ARG_INTEGER_PART, integerPart);
        }

        /**
         * Sets the {@link #ARG_FRACTIONAL_PART} argument.
         * @param fractionalPart Can be a string of digits of any size.
         * @return This instance.
         */
        public MoneyBuilder setFractionalPart(String fractionalPart) {
            return setStringArgument(TtsSpan.ARG_FRACTIONAL_PART, fractionalPart);
        }

        /**
         * Sets the {@link #ARG_CURRENCY} argument.
         * @param currency Should be a ISO4217 currency code, e.g. "USD".
         * @return This instance.
         */
        public MoneyBuilder setCurrency(String currency) {
            return setStringArgument(TtsSpan.ARG_CURRENCY, currency);
        }

        /**
         * Sets the {@link #ARG_QUANTITY} argument.
         * @param quantity
         * @return This instance.
         */
        public MoneyBuilder setQuantity(String quantity) {
            return setStringArgument(TtsSpan.ARG_QUANTITY, quantity);
        }
    }

    /**
     * A builder for TtsSpans of type {@link #TYPE_TELEPHONE}.
     */
    public static class TelephoneBuilder
            extends SemioticClassBuilder<TelephoneBuilder> {

        /**
         * Creates a TtsSpan of type {@link #TYPE_TELEPHONE}.
         */
        public TelephoneBuilder() {
            super(TtsSpan.TYPE_TELEPHONE);
        }

        /**
         * Creates a TtsSpan of type {@link #TYPE_TELEPHONE} and sets the
         * {@link #ARG_NUMBER_PARTS} argument.
         */
        public TelephoneBuilder(String numberParts) {
            this();
            setNumberParts(numberParts);
        }

        /**
         * Sets the {@link #ARG_COUNTRY_CODE} argument.
         * @param countryCode The country code can be a series of digits
         * optionally prefixed with a "+".
         * @return This instance.
         */
        public TelephoneBuilder setCountryCode(String countryCode) {
            return setStringArgument(TtsSpan.ARG_COUNTRY_CODE, countryCode);
        }

        /**
         * Sets the {@link #ARG_NUMBER_PARTS} argument.
         * @param numberParts The main telephone number. Can be a series of
         *     digits and letters separated by spaces, "/", "-" or ".".
         * @return This instance.
         */
        public TelephoneBuilder setNumberParts(String numberParts) {
            return setStringArgument(TtsSpan.ARG_NUMBER_PARTS, numberParts);
        }

        /**
         * Sets the {@link #ARG_EXTENSION} argument.
         * @param extension The extension can be a series of digits.
         * @return This instance.
         */
        public TelephoneBuilder setExtension(String extension) {
            return setStringArgument(TtsSpan.ARG_EXTENSION, extension);
        }
    }

    /**
     * A builder for TtsSpans of type {@link #TYPE_ELECTRONIC}.
     */
    public static class ElectronicBuilder
            extends SemioticClassBuilder<ElectronicBuilder> {

        /**
         * Creates a TtsSpan of type {@link #TYPE_ELECTRONIC}.
         */
        public ElectronicBuilder() {
            super(TtsSpan.TYPE_ELECTRONIC);
        }

        /**
         * Sets the {@link #ARG_USERNAME} and {@link #ARG_DOMAIN}
         *     arguments, representing an email address.
         * @param username The part before the @ in the email address.
         * @param domain The part after the @ in the email address.
         * @return This instance.
         */
        public ElectronicBuilder setEmailArguments(String username,
                                                   String domain) {
            return setDomain(domain).setUsername(username);
        }

        /**
         * Sets the {@link #ARG_PROTOCOL} argument.
         * @param protocol The protocol of the URI. Examples are "http" and
         *     "ftp".
         * @return This instance.
         */
        public ElectronicBuilder setProtocol(String protocol) {
            return setStringArgument(TtsSpan.ARG_PROTOCOL, protocol);
        }

        /**
         * Sets the {@link #ARG_USERNAME} argument.
         * @return This instance.
         */
        public ElectronicBuilder setUsername(String username) {
            return setStringArgument(TtsSpan.ARG_USERNAME, username);
        }

        /**
         * Sets the {@link #ARG_PASSWORD} argument.
         * @return This instance.
         */
        public ElectronicBuilder setPassword(String password) {
            return setStringArgument(TtsSpan.ARG_PASSWORD, password);
        }

        /**
         * Sets the {@link #ARG_DOMAIN} argument.
         * @param domain The domain, for example "source.android.com".
         * @return This instance.
         */
        public ElectronicBuilder setDomain(String domain) {
            return setStringArgument(TtsSpan.ARG_DOMAIN, domain);
        }

        /**
         * Sets the {@link #ARG_PORT} argument.
         * @return This instance.
         */
        public ElectronicBuilder setPort(int port) {
            return setIntArgument(TtsSpan.ARG_PORT, port);
        }

        /**
         * Sets the {@link #ARG_PATH} argument.
         * @param path For example "source/index.html".
         * @return This instance.
         */
        public ElectronicBuilder setPath(String path) {
            return setStringArgument(TtsSpan.ARG_PATH, path);
        }

        /**
         * Sets the {@link #ARG_QUERY_STRING} argument.
         * @param queryString For example "arg=value&argtwo=value".
         * @return This instance.
         */
        public ElectronicBuilder setQueryString(String queryString) {
            return setStringArgument(TtsSpan.ARG_QUERY_STRING, queryString);
        }

        /**
         * Sets the {@link #ARG_FRAGMENT_ID} argument.
         * @return This instance.
         */
        public ElectronicBuilder setFragmentId(String fragmentId) {
            return setStringArgument(TtsSpan.ARG_FRAGMENT_ID, fragmentId);
        }
    }

    /**
     * A builder for TtsSpans of type {@link #TYPE_DIGITS}.
     */
    public static class DigitsBuilder
            extends SemioticClassBuilder<DigitsBuilder> {

        /**
         * Creates a builder for a TtsSpan of type {@link #TYPE_DIGITS}.
         */
        public DigitsBuilder() {
            super(TtsSpan.TYPE_DIGITS);
        }

        /**
         * Creates a builder for a TtsSpan of type {@link #TYPE_DIGITS}
         * and sets the {@link #ARG_DIGITS} argument.
         */
        public DigitsBuilder(String digits) {
            this();
            setDigits(digits);
        }

        /**
         * Sets the {@link #ARG_DIGITS} argument.
         * @param digits A string of digits.
         * @return This instance.
         */
        public DigitsBuilder setDigits(String digits) {
            return setStringArgument(TtsSpan.ARG_DIGITS, digits);
        }
    }

    /**
     * A builder for TtsSpans of type {@link #TYPE_VERBATIM}.
     */
    public static class VerbatimBuilder
            extends SemioticClassBuilder<VerbatimBuilder> {

        /**
         * Creates a builder for a TtsSpan of type {@link #TYPE_VERBATIM}.
         */
        public VerbatimBuilder() {
            super(TtsSpan.TYPE_VERBATIM);
        }

        /**
         * Creates a builder for a TtsSpan of type {@link #TYPE_VERBATIM}
         * and sets the {@link #ARG_VERBATIM} argument.
         */
        public VerbatimBuilder(String verbatim) {
            this();
            setVerbatim(verbatim);
        }

        /**
         * Sets the {@link #ARG_VERBATIM} argument.
         * @param verbatim A string of characters that will be read verbatim,
         *     except whitespace.
         * @return This instance.
         */
        public VerbatimBuilder setVerbatim(String verbatim) {
            return setStringArgument(TtsSpan.ARG_VERBATIM, verbatim);
        }
    }
}