fmt
Loading...
Searching...
No Matches
color.cppm File Reference
module fmt

Terminal colour and text style support. More...

#include "fmt/macros.hpp"
#include <cerrno>
#include <climits>
#include <limits.h>
#include <stdint.h>
#include <stdio.h>
#include <string.h>
#include <version>
import fmt:format;
import std;

Classes

struct  fmt::Rgb
struct  fmt::detail::ColorType
class  fmt::TextStyle
struct  fmt::detail::AnsiColorEscape< Char >
struct  fmt::detail::StyledArg< T >
struct  fmt::Formatter< detail::StyledArg< T >, Char >

Enumerations

enum class  fmt::Color : uint32_t {
  kAliceBlue = 0xF0'F8FF , kAntiqueWhite = 0xFA'EBD7 , kAqua = 0x00'FFFF , kAquamarine = 0x7F'FFD4 ,
  kAzure = 0xF0'FFFF , kBeige = 0xF5'F5DC , kBisque = 0xFF'E4C4 , kBlack = 0x00'0000 ,
  kBlanchedAlmond = 0xFF'EBCD , kBlue = 0x00'00FF , kBlueViolet = 0x8A'2BE2 , kBrown = 0xA5'2A2A ,
  kBurlyWood = 0xDE'B887 , kCadetBlue = 0x5F'9EA0 , kChartreuse = 0x7F'FF00 , kChocolate = 0xD2'691E ,
  kCoral = 0xFF'7F50 , kCornflowerBlue = 0x64'95ED , kCornsilk = 0xFF'F8DC , kCrimson = 0xDC'143C ,
  kCyan = 0x00'FFFF , kDarkBlue = 0x00'008B , kDarkCyan = 0x00'8B8B , kDarkGoldenRod = 0xB8'860B ,
  kDarkGray = 0xA9'A9A9 , kDarkGreen = 0x00'6400 , kDarkKhaki = 0xBD'B76B , kDarkMagenta = 0x8B'008B ,
  kDarkOliveGreen = 0x55'6B2F , kDarkOrange = 0xFF'8C00 , kDarkOrchid = 0x99'32CC , kDarkRed = 0x8B'0000 ,
  kDarkSalmon = 0xE9'967A , kDarkSeaGreen = 0x8F'BC8F , kDarkSlateBlue = 0x48'3D8B , kDarkSlateGray = 0x2F'4F4F ,
  kDarkTurquoise = 0x00'CED1 , kDarkViolet = 0x94'00D3 , kDeepPink = 0xFF'1493 , kDeepSkyBlue = 0x00'BFFF ,
  kDimGray = 0x69'6969 , kDodgerBlue = 0x1E'90FF , kFireBrick = 0xB2'2222 , kFloralWhite = 0xFF'FAF0 ,
  kForestGreen = 0x22'8B22 , kFuchsia = 0xFF'00FF , kGainsboro = 0xDC'DCDC , kGhostWhite = 0xF8'F8FF ,
  kGold = 0xFF'D700 , kGoldenRod = 0xDA'A520 , kGray = 0x80'8080 , kGreen = 0x00'8000 ,
  kGreenYellow = 0xAD'FF2F , kHoneyDew = 0xF0'FFF0 , kHotPink = 0xFF'69B4 , kIndianRed = 0xCD'5C5C ,
  kIndigo = 0x4B'0082 , kIvory = 0xFF'FFF0 , kKhaki = 0xF0'E68C , kLavender = 0xE6'E6FA ,
  kLavenderBlush = 0xFF'F0F5 , kLawnGreen = 0x7C'FC00 , kLemonChiffon = 0xFF'FACD , kLightBlue = 0xAD'D8E6 ,
  kLightCoral = 0xF0'8080 , kLightCyan = 0xE0'FFFF , kLightGoldenRodYellow = 0xFA'FAD2 , kLightGray = 0xD3'D3D3 ,
  kLightGreen = 0x90'EE90 , kLightPink = 0xFF'B6C1 , kLightSalmon = 0xFF'A07A , kLightSeaGreen = 0x20'B2AA ,
  kLightSkyBlue = 0x87'CEFA , kLightSlateGray = 0x77'8899 , kLightSteelBlue = 0xB0'C4DE , kLightYellow = 0xFF'FFE0 ,
  kLime = 0x00'FF00 , kLimeGreen = 0x32'CD32 , kLinen = 0xFA'F0E6 , kMagenta = 0xFF'00FF ,
  kMaroon = 0x80'0000 , kMediumAquamarine = 0x66'CDAA , kMediumBlue = 0x00'00CD , kMediumOrchid = 0xBA'55D3 ,
  kMediumPurple = 0x93'70DB , kMediumSeaGreen = 0x3C'B371 , kMediumSlateBlue = 0x7B'68EE , kMediumSpringGreen = 0x00'FA9A ,
  kMediumTurquoise = 0x48'D1CC , kMediumVioletRed = 0xC7'1585 , kMidnightBlue = 0x19'1970 , kMintCream = 0xF5'FFFA ,
  kMistyRose = 0xFF'E4E1 , kMoccasin = 0xFF'E4B5 , kNavajoWhite = 0xFF'DEAD , kNavy = 0x00'0080 ,
  kOldLace = 0xFD'F5E6 , kOlive = 0x80'8000 , kOliveDrab = 0x6B'8E23 , kOrange = 0xFF'A500 ,
  kOrangeRed = 0xFF'4500 , kOrchid = 0xDA'70D6 , kPaleGoldenRod = 0xEE'E8AA , kPaleGreen = 0x98'FB98 ,
  kPaleTurquoise = 0xAF'EEEE , kPaleVioletRed = 0xDB'7093 , kPapayaWhip = 0xFF'EFD5 , kPeachPuff = 0xFF'DAB9 ,
  kPeru = 0xCD'853F , kPink = 0xFF'C0CB , kPlum = 0xDD'A0DD , kPowderBlue = 0xB0'E0E6 ,
  kPurple = 0x80'0080 , kRebeccaPurple = 0x66'3399 , kRed = 0xFF'0000 , kRosyBrown = 0xBC'8F8F ,
  kRoyalBlue = 0x41'69E1 , kSaddleBrown = 0x8B'4513 , kSalmon = 0xFA'8072 , kSandyBrown = 0xF4'A460 ,
  kSeaGreen = 0x2E'8B57 , kSeaShell = 0xFF'F5EE , kSienna = 0xA0'522D , kSilver = 0xC0'C0C0 ,
  kSkyBlue = 0x87'CEEB , kSlateBlue = 0x6A'5ACD , kSlateGray = 0x70'8090 , kSnow = 0xFF'FAFA ,
  kSpringGreen = 0x00'FF7F , kSteelBlue = 0x46'82B4 , kTan = 0xD2'B48C , kTeal = 0x00'8080 ,
  kThistle = 0xD8'BFD8 , kTomato = 0xFF'6347 , kTurquoise = 0x40'E0D0 , kViolet = 0xEE'82EE ,
  kWheat = 0xF5'DEB3 , kWhite = 0xFF'FFFF , kWhiteSmoke = 0xF5'F5F5 , kYellow = 0xFF'FF00 ,
  kYellowGreen = 0x9A'CD32
}
enum class  fmt::TerminalColor : uint8_t {
  kBlack = 30 , kRed = 31 , kGreen = 32 , kYellow = 33 ,
  kBlue = 34 , kMagenta = 35 , kCyan = 36 , kWhite = 37 ,
  kBrightBlack = 90 , kBrightRed = 91 , kBrightGreen = 92 , kBrightYellow = 93 ,
  kBrightBlue = 94 , kBrightMagenta = 95 , kBrightCyan = 96 , kBrightWhite = 97
}
enum class  fmt::Emphasis : uint8_t {
  kBold = 1 , kFaint = 1 << 1 , kItalic = 1 << 2 , kUnderline = 1 << 3 ,
  kBlink = 1 << 4 , kReverse = 1 << 5 , kConceal = 1 << 6 , kStrikethrough = 1 << 7
}

Functions

constexpr auto fmt::fg (detail::ColorType foreground) -> TextStyle
constexpr auto fmt::bg (detail::ColorType background) -> TextStyle
constexpr auto fmt::operator| (Emphasis lhs, Emphasis rhs) noexcept -> TextStyle
template<typename Char>
constexpr auto fmt::detail::makeForegroundColor (ColorType foreground) noexcept -> AnsiColorEscape< Char >
template<typename Char>
constexpr auto fmt::detail::makeBackgroundColor (ColorType background) noexcept -> AnsiColorEscape< Char >
template<typename Char>
constexpr auto fmt::detail::makeEmphasis (Emphasis em) noexcept -> AnsiColorEscape< Char >
template<typename Char>
auto fmt::detail::resetColor (Buffer< Char > &buffer) -> void
template<typename Char>
auto fmt::detail::vformatTo (Buffer< Char > &buf, TextStyle ts, BasicStringView< Char > fmt, BasicFormatArgs< BufferedContext< Char > > args) -> void
auto fmt::vprint (FILE *f, TextStyle ts, StringView fmt, FormatArgs args) -> void
template<typename... T>
auto fmt::print (FILE *f, TextStyle ts, FormatString< T... > fmt, T &&... args) -> void
template<typename... T>
auto fmt::print (TextStyle ts, FormatString< T... > fmt, T &&... args) -> void
auto fmt::vprintln (FILE *f, TextStyle ts, StringView fmt, FormatArgs args) -> void
template<typename... T>
auto fmt::println (FILE *f, TextStyle ts, FormatString< T... > fmt, T &&... args) -> void
template<typename... T>
auto fmt::println (TextStyle ts, FormatString< T... > fmt, T &&... args) -> void
auto fmt::vformat (TextStyle ts, StringView fmt, FormatArgs args) -> std::string
template<typename... T>
auto fmt::format (TextStyle ts, FormatString< T... > fmt, T &&... args) -> std::string
template<typename OutputIt>
requires (detail::IsOutputIterator<OutputIt, char>::value)
auto fmt::vformatTo (OutputIt out, TextStyle ts, StringView fmt, FormatArgs args) -> OutputIt
template<typename OutputIt, typename... T>
requires (detail::IsOutputIterator<OutputIt, char>::value)
auto fmt::formatTo (OutputIt out, TextStyle ts, FormatString< T... > fmt, T &&... args) -> OutputIt
template<typename T>
constexpr auto fmt::styled (const T &value, TextStyle ts) -> detail::StyledArg< remove_cvref_t< T > >

Detailed Description

Terminal colour and text style support.

Interface partition fmt:color.

Enumeration Type Documentation

◆ Color

enum class fmt::Color : uint32_t
exportstrong

A named 24-bit RGB colour, from the CSS colour list.

The value is a packed hex triple, so fmt::color::kRed is 0xFF0000 and an arbitrary colour can be had by casting: fmt::color(0x123456).

See also
terminal_color for palette colours that follow the terminal theme.

◆ Emphasis

enum class fmt::Emphasis : uint8_t
exportstrong

Text emphases, combinable with |.

Terminal support varies: bold and underline are near-universal, while blink, conceal and strikethrough are often ignored.

◆ TerminalColor

enum class fmt::TerminalColor : uint8_t
exportstrong

The sixteen standard terminal colours.

Unlike color, these are rendered using the terminal palette, so they follow the user's theme. Prefer them when the output should blend with the surrounding terminal.

Function Documentation

◆ bg()

auto fmt::bg ( detail::ColorType background) -> TextStyle
constexprexportnoexcept

Creates a style that sets the background colour.

Parameters
backgrounda color, terminal_color or rgb.
Returns
a style that can be combined with others using |.
See also
fg

◆ fg()

auto fmt::fg ( detail::ColorType foreground) -> TextStyle
constexprexportnoexcept

Creates a style that sets the foreground, that is the text, colour.

Parameters
foregrounda color, terminal_color or rgb.
Returns
a style that can be combined with others using |.

Example:

auto style = fmt::fg(fmt::color::kRed) | fmt::emphasis::kBold;
See also
bg

◆ format()

template<typename... T>
auto fmt::format ( TextStyle ts,
FormatString< T... > fmt,
T &&... args ) -> std::string
export

Formats args with the given style and returns the result as a string.

The returned string contains ANSI escape sequences, so it is intended for a terminal rather than a log file.

Parameters
tsthe style to apply.
fmta format string, checked at compile time.
argsthe arguments to format.
Returns
the formatted string, wrapped in escape sequences.

Example:

auto message = fmt::format(fmt::emphasis::kBold |

fg(fmt::color::kRed), "The answer is {}", 42);

◆ formatTo()

template<typename OutputIt, typename... T>
requires (detail::IsOutputIterator<OutputIt, char>::value)
auto fmt::formatTo ( OutputIt out,
TextStyle ts,
FormatString< T... > fmt,
T &&... args ) -> OutputIt
export

Formats args with the given style and writes the result to out.

Parameters
outan output iterator to write to.
tsthe style to apply.
fmta format string, checked at compile time.
argsthe arguments to format.
Returns
an iterator past the end of the output.

Example:

auto out = std::vector<char>();
fmt::formatTo(std::back_inserter(out),
               fmt::emphasis::kBold | fg(fmt::color::kRed), "{}",

42);

◆ operator|()

auto fmt::operator| ( Emphasis lhs,
Emphasis rhs ) -> TextStyle
constexprexportnoexcept

Combines two emphases into a style, so that bold | italic is a style.

◆ print() [1/2]

template<typename... T>
auto fmt::print ( FILE * f,
TextStyle ts,
FormatString< T... > fmt,
T &&... args ) -> void
export

Formats args with the given style and prints the result to f.

The style is emitted as ANSI escape sequences around the output and reset afterwards.

Parameters
fthe stream to write to.
tsthe style to apply.
fmta format string, checked at compile time.
argsthe arguments to format.
See also
styled to style one argument rather than the whole output.

◆ print() [2/2]

template<typename... T>
auto fmt::print ( TextStyle ts,
FormatString< T... > fmt,
T &&... args ) -> void
export

Formats args with the given style and prints the result to stdout.

Parameters
tsthe style to apply.
fmta format string, checked at compile time.
argsthe arguments to format.

Example:

fmt::print(fmt::emphasis::kBold | fg(fmt::color::kRed),
           "Elapsed time: {0:.2f} seconds", 1.23);

◆ println() [1/2]

template<typename... T>
auto fmt::println ( FILE * f,
TextStyle ts,
FormatString< T... > fmt,
T &&... args ) -> void
export

Formats args with the given style and prints the result to f, followed by a newline.

Parameters
fthe stream to write to.
tsthe style to apply.
fmta format string, checked at compile time.
argsthe arguments to format.
Note
Escape sequences are written unconditionally, so redirecting the stream to a file records them literally.

◆ println() [2/2]

template<typename... T>
auto fmt::println ( TextStyle ts,
FormatString< T... > fmt,
T &&... args ) -> void
export

Formats args with the given style and prints the result to stdout, followed by a newline.

Parameters
tsthe style to apply.
fmta format string, checked at compile time.
argsthe arguments to format.

Example:

fmt::println(fmt::emphasis::kBold | fg(fmt::color::kRed),
             "Elapsed time: {0:.2f} seconds", 1.23);

◆ styled()

template<typename T>
auto fmt::styled ( const T & value,
TextStyle ts ) -> detail::StyledArg< remove_cvref_t< T > >
constexprexport

Wraps a value so that it is formatted with the given style.

Unlike fmt::print(style, ...), which styles the whole output, this styles a single argument within it. The escape sequences are emitted around that argument only, and the style is reset afterwards.

Parameters
valuethe value to format.
tsthe style to apply to it.
Returns
an opaque wrapper to pass to a formatting function.

Example:

fmt::print("Elapsed time: {0:.2f} seconds",
           fmt::styled(1.23, fmt::fg(fmt::color::kGreen) |
                             fmt::bg(fmt::color::kBlue)));

◆ vformat()

auto fmt::vformat ( TextStyle ts,
StringView fmt,
FormatArgs args ) -> std::string
export

Type-erased form of format.

◆ vformatTo()

template<typename OutputIt>
requires (detail::IsOutputIterator<OutputIt, char>::value)
auto fmt::vformatTo ( OutputIt out,
TextStyle ts,
StringView fmt,
FormatArgs args ) -> OutputIt
export

Type-erased form of format_to for a styled output iterator.

Parameters
outan output iterator to write to.
tsthe style to apply.
fmta format string.
argsthe type-erased arguments.
Returns
an iterator past the end of the output.

◆ vprint()

auto fmt::vprint ( FILE * f,
TextStyle ts,
StringView fmt,
FormatArgs args ) -> void
export

Type-erased form of print.

◆ vprintln()

auto fmt::vprintln ( FILE * f,
TextStyle ts,
StringView fmt,
FormatArgs args ) -> void
export

Type-erased form of println.