Module: Toybox.StringUtil

Overview

The StringUtil module contains String utility functions

Since:

API Level 1.3.0

Classes Under Namespace

Classes: InvalidHexStringException

Constant Summary

CharacterEncoding

Since:

API Level 1.3.0

Name	Value	Since	Description
CHAR_ENCODING_UTF8	0	API Level 3.0.0

Representation

Since:

API Level 1.3.0

Name	Value	Since	Description
REPRESENTATION_STRING_BASE64	0	API Level 3.0.0
REPRESENTATION_STRING_HEX	1	API Level 3.0.0
REPRESENTATION_STRING_PLAIN_TEXT	2	API Level 3.0.0
REPRESENTATION_BYTE_ARRAY	3	API Level 3.0.0

Instance Method Summary

• charArrayToString(charArray as Lang.Array<Lang.Char>) as Lang.String

  Given an Array of Char objects, return the String equivalent.

• convertEncodedString(input as Lang.String or Lang.ByteArray, options as { :fromRepresentation as StringUtil.Representation, :toRepresentation as StringUtil.Representation, :encoding as StringUtil.CharacterEncoding }) as Lang.String or Lang.ByteArray

  Convert a String or ByteArray representation to a String or ByteArray representation whose underlying byte format corresponds to the provided input options.

• encodeBase64(string as Lang.String) as Lang.String

  Encodes a String in base64.

• utf8ArrayToString(utf8Array as Lang.Array<Lang.Number>) as Lang.String

  Given an Array of UTF-8 bytes, return the String equivalent.

Instance Method Details

charArrayToString(charArray as Lang.Array<Lang.Char>) as Lang.String

Given an Array of Char objects, return the String equivalent

Parameters:

• charArray — (Lang.Array) —

  An Array of Char objects

Returns:

• Lang.String —

  The String representation of the input Array

Since:

API Level 1.3.0

convertEncodedString(input as Lang.String or Lang.ByteArray, options as { :fromRepresentation as StringUtil.Representation, :toRepresentation as StringUtil.Representation, :encoding as StringUtil.CharacterEncoding }) as Lang.String or Lang.ByteArray

Convert a String or ByteArray representation to a String or ByteArray representation whose underlying byte format corresponds to the provided input options.

Parameters:

• input — (Lang.String, Lang.ByteArray) —

  Input that needs to be converted.

• options — (Lang.Dictionary)
  • :fromRepresentation — (StringUtil.Representation) —

    Required. A REPRESENTATION_* enum value indicating the representation from which the input should be converted.

  • :toRepresentation — (StringUtil.Representation) —

    Required. A REPRESENTATION_* enum value indicating the representation to which the input should be converted.

  • :encoding — (StringUtil.CharacterEncoding) —

    A CHAR_ENCODING_* value indicating the String encoding to use when generating a hex string or ByteArray when either the fromRepresentation or toRepresentation is set to REPRESENTATION_STRING_PLAIN_TEXT. Defaults to CHAR_ENCODING_UTF8 if not specified.

Returns:

• Lang.String, Lang.ByteArray —

  The converted String or ByteArray based on the provided options

Since:

API Level 3.0.0

Throws:

• (Lang.InvalidOptionsException) —

  Thrown if a required option is not set with a valid enumeration value.

encodeBase64(string as Lang.String) as Lang.String

Encodes a String in base64

Parameters:

• string — (Lang.String) —

  The string to encode

Returns:

• Lang.String —

  A base64 encoded String

Since:

API Level 1.3.0

utf8ArrayToString(utf8Array as Lang.Array<Lang.Number>) as Lang.String

Given an Array of UTF-8 bytes, return the String equivalent

Parameters:

• utf8Array — (Lang.Array) —

  An Array of UTF-8 bytes

Returns:

• Lang.String —

  The String representation of the input Array

Since:

API Level 1.3.0

Throws:

• (Lang.InvalidValueException) —

  Thrown if a the provided bytes contain an invalid UTF-8 sequence.