Skip to main content

ColoredString Class

ColoredString is Alia's built-in colored string class, used to represent strings that carry color information. It colors the string based on a string template raw and a Sheet (a mapping between colors and arrays of coloring positions).

Creating Colored Strings​

Using the Constructor​

const emptyCs = new ColoredString
const helloCs = new ColoredString ['Hello World']
const redColor = new Color ['#FF0000', 'Hex']
const colorSheet = new Sheet [['color', 'ranges'], [[redColor, [[0, 5]]]]]
const mappedCs = new ColoredString ['Hello World', colorSheet]

Constructor Parameters​

ParameterTypeDescription
strStringThe raw string, defaults to an empty string
colorsSheetThe color mapping table with headers ['color', 'ranges']

Constructor calls use array form: new ColoredString [str] passes only the raw string, while new ColoredString [str, colors] also passes the color mapping table. new Color [value, type] creates a color of the specified type.

Color Mapping Table (Sheet) Structure​

The color mapping table is a Sheet object with the following headers:

ColumnTypeDescription
colorColorThe color object
rangesArrayThe array of coloring positions, in the format [[from, to], ...]

Example:

const red = new Color ['#FF0000', 'Hex']
const blue = new Color ['#0000FF', 'Hex']
const colorSheet = new Sheet [['color', 'ranges'], [[red, [[0, 5], [10, 15]]], [blue, [[5, 10]]]]]

Instance Properties​

raw​

Returns the raw string.

const cs = new ColoredString ['Hello World']
print cs.raw

colors​

Returns the color mapping table (a Sheet object).

const redColor = new Color ['#FF0000', 'Hex']
const colorSheet = new Sheet [['color', 'ranges'], [[redColor, [[0, 5]]]]]
const cs = new ColoredString ['Hello', colorSheet]
print cs.colors.headers

Instance Methods​

color <Value color> at <Value ranges>​

Applies a color to the specified region.

Parameters:

  • color (Color): the color object
  • ranges (Array): the coloring range, in the format [from, to]

Returns: the current ColoredString object (supports chaining)

const redColor = new Color ['#FF0000', 'Hex']
const cs = new ColoredString ['Hello World']
cs.color redColor at [0, 5]
const blueColor = new Color ['#0000FF', 'Hex']
cs.color blueColor at [6, 11]

add <String other> with <Value color>​

Appends a string with the specified color.

Parameters:

  • other (String): the string to append
  • color (Color): the color object

Returns: the current ColoredString object (supports chaining)

const redColor = new Color ['#FF0000', 'Hex']
const cs = new ColoredString ['Hello']
cs.add ' World' with redColor
assert cs.raw == 'Hello World' error 'add result mismatch'
const blueColor = new Color ['#0000FF', 'Hex']
cs.add '!' with blueColor
assert cs.raw == 'Hello World!' error 'add chain mismatch'

toString​

Returns the string representation, whose content includes the raw string and a description of the color mapping.

const redColor = new Color ['#FF0000', 'Hex']
const cs = new ColoredString ['Hello']
cs.color redColor at [0, 5]
print call cs.toString

valueOf​

Returns the raw string.

const cs = new ColoredString ['Hello World']
print call cs.valueOf

Example Code​

const red = new Color ['#FF0000', 'Hex']
const green = new Color ['#00FF00', 'Hex']
const blue = new Color ['#0000FF', 'Hex']
const cs = new ColoredString ['Hello World']
cs.color red at [0, 5]
cs.color green at [6, 11]
cs.add '! ' with blue
cs.add 'Alia' with red
assert cs.raw == 'Hello World! Alia' error 'raw mismatch'
const colors = cs.colors
assert colors.data.length == 3 error 'colors length mismatch'
const redRanges = colors.lookup red returning 'ranges' in 'color'
print redRanges
const initSheet = new Sheet [['color', 'ranges'], [[red, [[0, 5]]], [blue, [[5, 10]]]]]
const cs2 = new ColoredString ['ABCDEFGHIJ', initSheet]
assert cs2.raw == 'ABCDEFGHIJ' error 'cs2 raw mismatch'

Notes​

  1. Coloring positions: [from, to] denotes the character range from index from (inclusive) to to (exclusive)
  2. Color mapping table: Stored internally as a Sheet object, upholding the principle that object keys must be keywords
  3. Object references: Color lookup is based on object reference (=== comparison); colors with the same value but different objects are treated as different colors

Next Steps​