The Smart Strings module provides string formatting with named placeholders, pluralization, and conditional text, based on SmartFormat.
Smart Strings build dynamic text from a single template that references values by name rather than by position. A template can pull values from objects or dictionaries, choose between phrasings, pluralize words, and format lists, which makes it well suited to localized text.
This module is enabled by default in all new projects. To enable it in an older project, do the following in the Unity Editor:
Alternatively, you can add this line to the Packages/manifest.json file to enable the module: "com.unity.modules.smartstrings": "1.0.0",
| Class | Description |
|---|---|
| AdditionalFormatData | Provides additional information to the smart formatter for sources and formatters to use during formatting. |
| BoolVariable | A IVariable that holds a single bool value. |
| ByteVariable | A IVariable that holds a single byte value. |
| ChooseFormatter | Outputs one of several literal options, selected according to the input value. |
| ConditionalFormatter | Formats primitive types by matching them against condition patterns. |
| CustomPluralRuleProvider | Provides custom plural rules to Smart.Format. |
| DefaultFormatter | Performs default formatting, using the same logic as string.Format. |
| DefaultSource | Evaluates an index-based Selector. Include this source, if an indexed source shall be used just the way string.Format does. |
| DictionarySource | Evaluates sources of types Collections.IDictionary, generic Collections.Generic.IDictionary_2 and dynamic Dynamic.ExpandoObject. Include this source, if any of these types shall be used. |
| DoubleVariable | A IVariable that holds a single double value. |
| FloatVariable | A IVariable that holds a single float value. |
| Format | Represents a parsed format string. Contains a list of FormatItems, including LiteralTexts and Placeholders. Note: Format is IDisposable. |
| FormatDelegate | Wraps a delegate so that it can be used as a parameter to any string-formatting method (such as String.Format). For example: var textWithLink = string.Format("Please click on {0:this link}.", new FormatDelegate((text) => Html.ActionLink(text, "SomeAction")); |
| FormatDetails | Contains extra information about the item currently being formatted. These objects are not often used, so they are all wrapped up here. |
| FormatItem | Base class that represents a substring of text from a parsed format string. |
| FormatterBase | Base class that implements common IFormatter functionality. |
| FormatterSettings | Class for SmartFormatter settings. Properties should be considered as 'init-only' like implemented in C# 9. Any changes after passing settings as argument to CTORs may not have effect. |
| FormattingErrorEventArgs | Supplies information about formatting errors. |
| FormattingException | An exception caused while attempting to output the format. |
| FormattingInfo | The class contains the fields and methods which are necessary for formatting. |
| IntVariable | A IVariable that holds a single integer value. |
| IsMatchFormatter | Formats values by matching them against a regular expression, and can output matching group values. |
| KeyValuePairSource | Evaluates a Selector with a Collections.Generic.KeyValuePair_2. The key must be string, the value must be an Object. |
| ListFormatter | Formats each item individually when the source value is an array (or supports ICollection). Syntax: #1: "format|spacer" #2: "format|spacer|last spacer" #3: "format|spacer|last spacer|two spacer" The format will be used for each item in the collection, the spacer will be between all items, and the last spacer will replace the spacer for the last item only. Example: CustomFormat("{Dates:D|; |; and }", {#1/1/2000#, #12/31/2999#, #9/9/9999#}) = "January 1, 2000; December 31, 2999; and September 9, 9999" In this example, format = "D", spacer = "; ", and last spacer = "; and " Advanced: Composite Formatting is allowed in the format by using nested braces. If a nested item is detected, Composite formatting will be used. Example: CustomFormat("{Sizes:{Width}x{Height}|, }", {new Size(4,3), new Size(16,9)}) = "4x3, 16x9" In this example, format = "{Width}x{Height}". Notice the nested braces. |
| LiteralText | Represents the literal text that is found in a parsed format string. |
| LongVariable | A IVariable that holds a single long value. |
| NestedVariablesGroup | Provides a reference to a VariablesGroupAsset. |
| NullFormatter | Formats null values. |
| ObjectVariable | A IVariable that can reference an Object instance. |
| Parser | Parses a format string. |
| ParserSettings | Class for Parser settings. Properties should be considered as 'init-only' like implemented in C# 9. Any changes after passing settings as argument to CTORs may not have effect. |
| ParsingErrorEventArgs | Supplies information about parsing errors. |
| ParsingErrors | Represents parsing errors in a format string. This exception only gets thrown when Parser.ErrorAction is set to ThrowError. |
| PersistentVariablesSource | Provides global or local values that do not need to be passed in as arguments when formatting a string. The smart string should take the format {groupName.variableName}. e.g {global.player-score}. Note: The group name and variable names must not contain any spaces. |
| Placeholder | A placeholder is the part of a format string between the {braces}. |
| PluralLocalizationFormatter | Formats values according to culture-specific pluralization rules. |
| PluralRules | Maps two-letter ISO language codes to their pluralization rules. PluralRules are used by extensions like TimeFormatter and PluralLocalizationFormatter. |
| PoolingException | Represents an Exception thrown by the pooling subsystem. |
| PropertiesSource | Evaluates a selector by reading the member of the same name through the Unity.Properties data model. |
| SByteVariable | A IVariable that holds a single signed byte value. |
| Selector | Represents a single selector in a Placeholder. E.g.: {selector0.selector1?.selector2}, while "." and "?." and "?[]" are operators. |
| ShortVariable | A IVariable that holds a single short value. |
| Smart | This class holds a Smart.Default instance of a SmartFormatter. The default instance has all extensions registered. For optimized performance, create a SmartFormatter instance and register the particular extensions that are needed.Smart methods are not thread safe. |
| SmartExtensions | Provides extension methods that apply Smart String formatting to Text.StringBuilder, IO.TextWriter, and string. |
| SmartFormatter | Constructs formatted strings by invoking each registered source and formatter extension. |
| SmartSettings | Smart settings to be applied for parsing and formatting. SmartSettings are used to initialize instances. Properties should be considered as 'init-only' like implemented in C# 9. Any changes after passing settings as argument to CTORs may not have effect, unless explicitly mentioned. |
| SmartStringsSettings | Project-wide Smart Strings settings. The active instance is included in player builds as a preloaded asset and exposes the default SmartStringsSettings.SmartFormatter used to format Smart Strings. |
| Source | The base class for ISource extension classes. |
| StringOutput | Wraps a Text.StringBuilder so it can be used for output. |
| StringSource | Evaluates a Selector with a string as ISelectorInfo.CurrentValue. Include this source for handling string and its extension methods. |
| StringVariable | A IVariable that holds a single string value. |
| SubStringFormatter | Outputs part of an input string. |
| TemplateFormatter | Registers reusable templates and applies them by name. |
| TextWriterOutput | Wraps a IO.TextWriter so that it can be used for output. |
| TimeFormatter | A formatter that outputs TimeSpan values as human-readable text. |
| UIntVariable | A IVariable that holds a single unsigned integer value. |
| ULongVariable | A IVariable that holds a single unsigned long value. |
| UShortVariable | A IVariable that holds a single unsigned short value. |
| Variable<T0> | Base class for all single source variables. Inherit from this class for storage for a single serialized source value that will send a value changed event when Variable<T0>.Value is changed. This will trigger any localized string that is currently using the variable to update. |
| VariablesGroupAsset | Collection of IVariable that can be used during formatting of a localized string. |
| Enumeration | Description |
|---|---|
| CaseSensitivityType | Options for whether strings are processed case-sensitively. |
| FormatErrorAction | Determines how format errors are handled. |
| ParseErrorAction | Determines how parsing errors are handled. |
| TimeSpanFormatOptions | Determines all options for time formatting.This one value actually contains 4 settings:Abbreviate / AbbreviateOffLessThan / LessThanOffTruncate Auto / Shortest / Fill / FullRange MilliSeconds / Seconds / Minutes / Hours / Days / Weeks (Min / Max) |