# Global.String

> The JavaScript built-in String type.

- Source: https://titaniumsdk.com/docs/sdk/main/Global.String
- Titanium SDK version: main
- Kind: module
- Platforms: Android, iPhone, iPad, macOS

This module contains Titanium-only extensions for formatting data into locale-specific strings. 
The target locale is configured by the user in the device's system Settings.

## Methods

### format

- Platforms: Android, iPhone, iPad, macOS

Formats a string using `printf`-style substitution.

The format string follows the 
[IEEE printf specification](http://pubs.opengroup.org/onlinepubs/009695399/functions/printf.html).

For each "conversion specification" (ie. `%s` for a string or `%d` for a number) used inside
the string, `formatString` argument, the respective value is substituted from the
argument list. For example:

``` js
var forename = 'Paul';
var number = 21;
var message = String.format('Welcome, %s! You are visitor number %d', forename, number);
Ti.API.info(message);
```

Parameters:

- `formatString` (String): An IEEE `printf`-style string, containing zero or more conversion specifications.
- `value` (String | Number, repeatable): Values to substitute into the `formatString`. The method expects a variable number of `value` arguments, one for each `%` conversion specification in the format string. Optional on Android.

Returns: String - Formatted string.

### formatCurrency

- Platforms: Android, iPhone, iPad, macOS

Formats a number into the currency format, including currency symbol, of the locale 
configured for the system.

Parameters:

- `value` (Number): Currency value.

Returns: String - Formatted, localized string.

### formatDate

- Platforms: Android, iPhone, iPad, macOS

Formats a date into the date format of the locale configured for the system.

Parameters:

- `date` (Date): Date to format.
- `format` (String, optional): Date format to use. One of 'short', 'medium', 'long' or 'full'. Default: `short`.

Returns: String - Formatted, localized string.

### formatDecimal

- Platforms: Android, iPhone, iPad, macOS

Formats a number into the decimal format, including decimal symbol, of the locale 
configured for the system.

The localized string created by this method can be parsed be parsed back to a number
via the [Titanium.Locale.parseDecimal](https://titaniumsdk.com/docs/sdk/Titanium.Locale.md#parseDecimal) method.

Parameters:

- `value` (Number): Value to format.
- `locale` (String, optional): Locale string. For example, `en-US` for US English.
- `pattern` (String, optional): Format pattern.

Returns: String - String representation of the specified number, using a locale-specific decimal symbol, 
if required.

### formatTime

- Platforms: Android, iPhone, iPad, macOS

Formats a date into the time format of the locale configured for the system.

On Android, this method returns the short format.

Parameters:

- `date` (Date): Date to format.
- `format` (String, optional): Date format to use. One of 'short', 'medium', or 'long' (iOS only.) Default: `short`.

Returns: String - Formatted, localized string.

---

- This corpus documents Titanium SDK 13.4.1. Anything here that does not name a version describes 13.4.1.
- Titanium is maintained by TiDev. The Appcelerator toolchain is retired: there is no `appc` CLI, no Appcelerator Studio and no hosted build service. The supported CLI is `titanium` on npm, invoked as `ti`.