# std/colors

Theme:

- Manual
- Standard library
- Index
- Compiler docs
- Fusion docs
- devel, stable

Search:
Source Edit

This module implements color handling for Nim, namely color mixing and parsing the CSS color names.

# Imports

strutils, algorithm

# Types

    Color = distinct int

  A color stored as RGB, e.g. `0xff00cc`. Source Edit

# Consts

    colAliceBlue = 15792383

  Source Edit

    colAntiqueWhite = 16444375

  Source Edit

    colAqua = 65535

  Source Edit

    colAquamarine = 8388564

  Source Edit

    colAzure = 15794175

  Source Edit

    colBeige = 16119260

  Source Edit

    colBisque = 16770244

  Source Edit

    colBlack = 0

  Source Edit

    colBlanchedAlmond = 16772045

  Source Edit

    colBlue = 255

  Source Edit

    colBlueViolet = 9055202

  Source Edit

    colBrown = 10824234

  Source Edit

    colBurlyWood = 14596231

  Source Edit

    colCadetBlue = 6266528

  Source Edit

    colChartreuse = 8388352

  Source Edit

    colChocolate = 13789470

  Source Edit

    colCoral = 16744272

  Source Edit

    colCornflowerBlue = 6591981

  Source Edit

    colCornsilk = 16775388

  Source Edit

    colCrimson = 14423100

  Source Edit

    colCyan = 65535

  Source Edit

    colDarkBlue = 139

  Source Edit

    colDarkCyan = 35723

  Source Edit

    colDarkGoldenRod = 12092939

  Source Edit

    colDarkGray = 11119017

  Source Edit

    colDarkGreen = 25600

  Source Edit

    colDarkGrey = 11119017

  Source Edit

    colDarkKhaki = 12433259

  Source Edit

    colDarkMagenta = 9109643

  Source Edit

    colDarkOliveGreen = 5597999

  Source Edit

    colDarkorange = 16747520

  Source Edit

    colDarkOrchid = 10040012

  Source Edit

    colDarkRed = 9109504

  Source Edit

    colDarkSalmon = 15308410

  Source Edit

    colDarkSeaGreen = 9419919

  Source Edit

    colDarkSlateBlue = 4734347

  Source Edit

    colDarkSlateGray = 3100495

  Source Edit

    colDarkSlateGrey = 3100495

  Source Edit

    colDarkTurquoise = 52945

  Source Edit

    colDarkViolet = 9699539

  Source Edit

    colDeepPink = 16716947

  Source Edit

    colDeepSkyBlue = 49151

  Source Edit

    colDimGray = 6908265

  Source Edit

    colDimGrey = 6908265

  Source Edit

    colDodgerBlue = 2003199

  Source Edit

    colFireBrick = 11674146

  Source Edit

    colFloralWhite = 16775920

  Source Edit

    colForestGreen = 2263842

  Source Edit

    colFuchsia = 16711935

  Source Edit

    colGainsboro = 14474460

  Source Edit

    colGhostWhite = 16316671

  Source Edit

    colGold = 16766720

  Source Edit

    colGoldenRod = 14329120

  Source Edit

    colGray = 8421504

  Source Edit

    colGreen = 32768

  Source Edit

    colGreenYellow = 11403055

  Source Edit

    colGrey = 8421504

  Source Edit

    colHoneyDew = 15794160

  Source Edit

    colHotPink = 16738740

  Source Edit

    colIndianRed = 13458524

  Source Edit

    colIndigo = 4915330

  Source Edit

    colIvory = 16777200

  Source Edit

    colKhaki = 15787660

  Source Edit

    colLavender = 15132410

  Source Edit

    colLavenderBlush = 16773365

  Source Edit

    colLawnGreen = 8190976

  Source Edit

    colLemonChiffon = 16775885

  Source Edit

    colLightBlue = 11393254

  Source Edit

    colLightCoral = 15761536

  Source Edit

    colLightCyan = 14745599

  Source Edit

    colLightGoldenRodYellow = 16448210

  Source Edit

    colLightGray = 13882323

  Source Edit

    colLightGreen = 9498256

  Source Edit

    colLightGrey = 13882323

  Source Edit

    colLightPink = 16758465

  Source Edit

    colLightSalmon = 16752762

  Source Edit

    colLightSeaGreen = 2142890

  Source Edit

    colLightSkyBlue = 8900346

  Source Edit

    colLightSlateGray = 7833753

  Source Edit

    colLightSlateGrey = 7833753

  Source Edit

    colLightSteelBlue = 11584734

  Source Edit

    colLightYellow = 16777184

  Source Edit

    colLime = 65280

  Source Edit

    colLimeGreen = 3329330

  Source Edit

    colLinen = 16445670

  Source Edit

    colMagenta = 16711935

  Source Edit

    colMaroon = 8388608

  Source Edit

    colMediumAquaMarine = 6737322

  Source Edit

    colMediumBlue = 205

  Source Edit

    colMediumOrchid = 12211667

  Source Edit

    colMediumPurple = 9662683

  Source Edit

    colMediumSeaGreen = 3978097

  Source Edit

    colMediumSlateBlue = 8087790

  Source Edit

    colMediumSpringGreen = 64154

  Source Edit

    colMediumTurquoise = 4772300

  Source Edit

    colMediumVioletRed = 13047173

  Source Edit

    colMidnightBlue = 1644912

  Source Edit

    colMintCream = 16121850

  Source Edit

    colMistyRose = 16770273

  Source Edit

    colMoccasin = 16770229

  Source Edit

    colNavajoWhite = 16768685

  Source Edit

    colNavy = 128

  Source Edit

    colOldLace = 16643558

  Source Edit

    colOlive = 8421376

  Source Edit

    colOliveDrab = 7048739

  Source Edit

    colOrange = 16753920

  Source Edit

    colOrangeRed = 16729344

  Source Edit

    colOrchid = 14315734

  Source Edit

    colPaleGoldenRod = 15657130

  Source Edit

    colPaleGreen = 10025880

  Source Edit

    colPaleTurquoise = 11529966

  Source Edit

    colPaleVioletRed = 14381203

  Source Edit

    colPapayaWhip = 16773077

  Source Edit

    colPeachPuff = 16767673

  Source Edit

    colPeru = 13468991

  Source Edit

    colPink = 16761035

  Source Edit

    colPlum = 14524637

  Source Edit

    colPowderBlue = 11591910

  Source Edit

    colPurple = 8388736

  Source Edit

    colRebeccaPurple = 6697881

  Source Edit

    colRed = 16711680

  Source Edit

    colRosyBrown = 12357519

  Source Edit

    colRoyalBlue = 4286945

  Source Edit

    colSaddleBrown = 9127187

  Source Edit

    colSalmon = 16416882

  Source Edit

    colSandyBrown = 16032864

  Source Edit

    colSeaGreen = 3050327

  Source Edit

    colSeaShell = 16774638

  Source Edit

    colSienna = 10506797

  Source Edit

    colSilver = 12632256

  Source Edit

    colSkyBlue = 8900331

  Source Edit

    colSlateBlue = 6970061

  Source Edit

    colSlateGray = 7372944

  Source Edit

    colSlateGrey = 7372944

  Source Edit

    colSnow = 16775930

  Source Edit

    colSpringGreen = 65407

  Source Edit

    colSteelBlue = 4620980

  Source Edit

    colTan = 13808780

  Source Edit

    colTeal = 32896

  Source Edit

    colThistle = 14204888

  Source Edit

    colTomato = 16737095

  Source Edit

    colTurquoise = 4251856

  Source Edit

    colViolet = 15631086

  Source Edit

    colWheat = 16113331

  Source Edit

    colWhite = 16777215

  Source Edit

    colWhiteSmoke = 16119285

  Source Edit

    colYellow = 16776960

  Source Edit

    colYellowGreen = 10145074

  Source Edit

# Procs

    proc `$`(c: Color): string {....raises: [], tags: [], forbids: [].}

  Converts a color into its textual representation.

  Example:

      assert $colFuchsia == "#FF00FF"

  Source Edit

    proc `+`(a, b: Color): Color {....raises: [], tags: [], forbids: [].}

  Adds two colors.

  This uses saturated arithmetic, so that each color component cannot overflow (255 is used as a maximum).

  Example:

      var
        a = Color(0xaa_00_ff)
        b = Color(0x11_cc_cc)
      assert a + b == Color(0xbb_cc_ff)

  Source Edit

    proc `-`(a, b: Color): Color {....raises: [], tags: [], forbids: [].}

  Subtracts two colors.

  This uses saturated arithmetic, so that each color component cannot underflow (0 is used as a minimum).

  Example:

      var
        a = Color(0xff_33_ff)
        b = Color(0x11_ff_cc)
      assert a - b == Color(0xee_00_33)

  Source Edit

    proc `==`(a, b: Color): bool {.borrow, ...raises: [], tags: [], forbids: [].}

  Compares two colors.

      var
        a = Color(0xff_00_ff)
        b = colFuchsia
        c = Color(0x00_ff_cc)
      assert a == b
      assert not (a == c)

  Source Edit

    proc extractRGB(a: Color): tuple[r, g, b: range[0 .. 255]] {....raises: [],
        tags: [], forbids: [].}

  Extracts the red/green/blue components of the color `a`.

  Example:

      var
        a = Color(0xff_00_ff)
        b = Color(0x00_ff_cc)
      type
        Col = range[0..255]
      # assert extractRGB(a) == (r: 255.Col, g: 0.Col, b: 255.Col)
      # assert extractRGB(b) == (r: 0.Col, g: 255.Col, b: 204.Col)
      echo extractRGB(a)
      echo typeof(extractRGB(a))
      echo extractRGB(b)
      echo typeof(extractRGB(b))

  Source Edit

    proc intensity(a: Color; f: float): Color {....raises: [], tags: [], forbids: [].}

  Returns `a` with intensity `f`. `f` should be a float from 0.0 (completely dark) to 1.0 (full color intensity).

  Example:

      var
        a = Color(0xff_00_ff)
        b = Color(0x00_42_cc)
      assert a.intensity(0.5) == Color(0x80_00_80)
      assert b.intensity(0.5) == Color(0x00_21_66)

  Source Edit

    proc isColor(name: string): bool {....raises: [], tags: [], forbids: [].}

  Returns true if `name` is a known color name or a hexadecimal color prefixed with `#`. Case insensitive.

  Example:

      var
        a = "silver"
        b = "#0179fc"
        c = "#zzmmtt"
      assert a.isColor
      assert b.isColor
      assert not c.isColor

  Source Edit

    proc parseColor(name: string): Color {....raises: [ValueError], tags: [],
                                           forbids: [].}

  Parses `name` to a color value.

  If no valid color could be parsed `ValueError` is raised. Case insensitive.

  Example:

      var
        a = "silver"
        b = "#0179fc"
        c = "#zzmmtt"
      assert parseColor(a) == Color(0xc0_c0_c0)
      assert parseColor(b) == Color(0x01_79_fc)
      doAssertRaises(ValueError): discard parseColor(c)

  Source Edit

    proc rgb(r, g, b: range[0 .. 255]): Color {....raises: [], tags: [], forbids: [].}

  Constructs a color from RGB values.

  Example:

      assert rgb(0, 255, 128) == Color(0x00_ff_80)

  Source Edit

# Templates

    template mix(a, b: Color; fn: untyped): untyped

  Uses `fn` to mix the colors `a` and `b`.

  `fn` is invoked for each component R, G, and B. If `fn`'s result is not in the `range[0..255]`, it will be saturated to be so.

  Example:

      var
        a = Color(0x0a2814)
        b = Color(0x050a03)

      proc myMix(x, y: int): int =
        2 * x - 3 * y

      assert mix(a, b, myMix) == Color(0x05_32_1f)

  Source Edit