ASCII

ASCII related operations. More...

Namespaces
namespace	mtcore::ascii
	ASCII-related methods for parsing and character classification Split into its own namespace to allow for clear differentiation from any unicode-related methods.

Functions
bool	mtcore::ascii::is_digit (const char c)
	Checks if a character is an ASCII digit (0-9)
bool	mtcore::ascii::is_hex (const char c)
	Checks if a character is an ASCII hex digit (0-9, a-f, A-F)
bool	mtcore::ascii::is_hex_str (Slice< const char > str)
	Checks if a string is composed of only hex characters Will return false if string is empty.
bool	mtcore::ascii::is_int_str (Slice< const char > str)
	Checks if a string is composed of only integer characters Will return false if string is empty.
bool	mtcore::ascii::is_pos_int_str (Slice< const char > str)
	Checks if a string is composed of only positive integer characters Will return false if string is empty.
template<typename Out = i32>
Result< Out, AsciiNumericParseError >	mtcore::ascii::hex_to_int (const Slice< const char > &parse)
	Tries to parse an ASCII hex string into an integer Will return an error if the parsed string does not fit.
template<typename Out = i32>
Result< Out, AsciiNumericParseError >	mtcore::ascii::base10_to_int (const Slice< const char > &parse)
	Tries to parse an ASCII numeric string into an integer Will return an error if the parsed string does not fit.
Result< char, UnescapeError >	mtcore::ascii::unescape_char (Slice< const char > str, char escapeChar='\\')
	Unescapes the first (potentially) escaped character in a character sequence If the sequence is empty, will return an error.
template<typename Writer>
Result< size_t, std::variant< typename Writer::ErrType, UnescapeError > >	mtcore::ascii::write_unescaped (Writer &writer, Slice< const char > str, char escapeChar='\\')
	Writes unescaped ASCII characters to a stream Note: This does NOT support writing Unicode escape codes at this time (so \uhhhh or \Uhhhhhhhh)

Detailed Description

ASCII related operations.

Function Documentation

base10_to_int()

template<typename Out = i32>

Result< Out, AsciiNumericParseError > mtcore::ascii::base10_to_int

(

const Slice< const char > &

parse

)

Tries to parse an ASCII numeric string into an integer Will return an error if the parsed string does not fit.

Template Parameters

Out	Out integer type

Parameters

parse

ASCII string to parse

Returns

Parsed value (or error)

Definition at line 244 of file ascii.hpp.

                                                                                      {
      Out res = 0;
      if (!parse.head || !parse.len) {
        return error(AsciiNumericParseError::INVALID_SLICE);
      }
 
      bool negate = false;
      auto s      = parse;
      if (s[0] == '-') {
        negate = true;
        s      = s.sub(1);
      }
      else if (s[0] == '+') {
        s = s.sub(1);
      }
 
      if (negate && !std::numeric_limits<Out>::is_signed) {
        return error(AsciiNumericParseError::INVALID_SIGN);
      }
 
      if (s.size() == 0) {
        return error(AsciiNumericParseError::INVALID_INPUT);
      }
 
      char ch;
      auto it = s.iter();
      while (it.next().copy_if_present(ch)) {
        if (ch == ',') {
          continue;
        }
        if (!is_digit(ch)) {
          return error(AsciiNumericParseError::INVALID_INPUT);
        }
 
        auto old = res;
        // Try to detect overflows before they happen (it's undefined behavior if they happen)
        if (negate) {
          if (res < std::numeric_limits<Out>::min() / 10) {
            return error(AsciiNumericParseError::OVERFLOW_DETECTED);
          }
        }
        else {
          if (res > std::numeric_limits<Out>::max() / 10) {
            return error(AsciiNumericParseError::OVERFLOW_DETECTED);
          }
        }
        res *= 10;
 
        auto addAmt = static_cast<Out>(ch - '0');
        if (negate) {
          if constexpr (std::is_signed_v<Out>) {
            // Try to detect overflows before they happen (it's undefined behavior if they happen)
            if (res != 0 && std::abs(std::numeric_limits<Out>::min() - res) < addAmt) {
              return error(AsciiNumericParseError::OVERFLOW_DETECTED);
            }
            addAmt = -addAmt;
          }
          else {
            unreachable();
          }
        }
        // Try to detect overflows before they happen (it's undefined behavior if they happen)
        else if (std::numeric_limits<Out>::max() - res < addAmt) {
          return error(AsciiNumericParseError::OVERFLOW_DETECTED);
        }
        res += addAmt;
 
        if (!negate && old > res) {
          return error(AsciiNumericParseError::OVERFLOW_DETECTED);
        }
        else if (negate && old < res) {
          return error(AsciiNumericParseError::OVERFLOW_DETECTED);
        }
      }
      return res;
    }

Here is the call graph for this function:

Here is the caller graph for this function:

hex_to_int()

template<typename Out = i32>

Result< Out, AsciiNumericParseError > mtcore::ascii::hex_to_int

(

const Slice< const char > &

parse

)

Tries to parse an ASCII hex string into an integer Will return an error if the parsed string does not fit.

Template Parameters

Out	Out integer type

Parameters

parse

ASCII string to parse

Returns

Parsed value (or error)

Definition at line 156 of file ascii.hpp.

                                                                                   {
      Out res = 0;
      if (!parse.head || !parse.len) {
        return error(AsciiNumericParseError::INVALID_SLICE);
      }
 
      bool negate = false;
      auto s      = parse;
      if (s[0] == '-') {
        negate = true;
        s      = s.sub(1);
      }
      else if (s[0] == '+') {
        s = s.sub(1);
      }
 
      if (negate && !std::numeric_limits<Out>::is_signed) {
        return error(AsciiNumericParseError::INVALID_SIGN);
      }
 
      if (s.size() == 0) {
        return error(AsciiNumericParseError::INVALID_INPUT);
      }
 
      if (s.size() > 2 && s[0] == '0' && s[1] == 'x') {
        s = s.sub(2);
      }
      else if (s.size() > 1 && s[0] == 'x') {
        s = s.sub(1);
      }
 
      char ch;
      auto it = s.iter();
      while (it.next().copy_if_present(ch)) {
        if (ch == ',') {
          continue;
        }
        if (!is_hex(ch)) {
          return error(AsciiNumericParseError::INVALID_INPUT);
        }
 
        auto old = res;
        // Try to detect overflows before they happen (it's undefined behavior if they happen)
        if (negate) {
          if (res < std::numeric_limits<Out>::min() / 16) {
            return error(AsciiNumericParseError::OVERFLOW_DETECTED);
          }
        }
        else {
          if (res > std::numeric_limits<Out>::max() / 16) {
            return error(AsciiNumericParseError::OVERFLOW_DETECTED);
          }
        }
        res *= 16;
 
        auto addAmt = (is_digit(ch)) ? ch - '0' : (ch | 0b0100000) - 'a' + 10;
        // Try to detect overflows before they happen (it's undefined behavior if they happen)
        if (negate) {
          if (res != 0 && std::abs(std::numeric_limits<Out>::min() - res) < addAmt) {
            return error(AsciiNumericParseError::OVERFLOW_DETECTED);
          }
          addAmt = -addAmt;
        }
        // Try to detect overflows before they happen (it's undefined behavior if they happen)
        else if (std::numeric_limits<Out>::max() - res < addAmt) {
          return error(AsciiNumericParseError::OVERFLOW_DETECTED);
        }
        res += addAmt;
 
        if (!negate && old > res) {
          return error(AsciiNumericParseError::OVERFLOW_DETECTED);
        }
        else if (negate && old < res) {
          return error(AsciiNumericParseError::OVERFLOW_DETECTED);
        }
      }
      return res;
    }

Here is the call graph for this function:

Here is the caller graph for this function:

is_digit()

bool mtcore::ascii::is_digit ( const char c )

inline

Checks if a character is an ASCII digit (0-9)

Parameters

c	Character to check

Definition at line 51 of file ascii.hpp.

{ return c >= '0' && c <= '9'; }

Here is the caller graph for this function:

is_hex()

bool mtcore::ascii::is_hex ( const char c )

inline

Checks if a character is an ASCII hex digit (0-9, a-f, A-F)

Parameters

c	Character to check

Definition at line 58 of file ascii.hpp.

                                     {
      if (is_digit(c)) {
        return true;
      }
      const auto lower = (c | 0b0100000);
      return lower >= 'a' && lower <= 'f';
    }

Here is the call graph for this function:

Here is the caller graph for this function:

is_hex_str()

bool mtcore::ascii::is_hex_str ( Slice< const char > str )

inline

Checks if a string is composed of only hex characters Will return false if string is empty.

Parameters

str	String to check

Definition at line 72 of file ascii.hpp.

                                                  {
      if (str.empty()) {
        return false;
      }
 
      auto iter = str.iter();
      char cur;
      while (iter.next().copy_if_present(cur)) {
        if (!is_hex(cur)) {
          return false;
        }
      }
      return true;
    }

Here is the call graph for this function:

is_int_str()

bool mtcore::ascii::is_int_str ( Slice< const char > str )

inline

Checks if a string is composed of only integer characters Will return false if string is empty.

Parameters

str	String to check

Definition at line 93 of file ascii.hpp.

                                                  {
      if (str.empty()) {
        return false;
      }
 
      auto iter = str.iter();
      char cur;
      bool first = true;
      bool digit = false;
      while (iter.next().copy_if_present(cur)) {
        if (first) {
          first = false;
          if (cur == '+' || cur == '-') {
            continue;
          }
        }
        if (!is_digit(cur)) {
          return false;
        }
        digit = true;
      }
      return digit;
    }

Here is the call graph for this function:

is_pos_int_str()

bool mtcore::ascii::is_pos_int_str ( Slice< const char > str )

inline

Checks if a string is composed of only positive integer characters Will return false if string is empty.

Parameters

str	String to check

Definition at line 123 of file ascii.hpp.

                                                      {
      if (str.empty()) {
        return false;
      }
 
      auto iter = str.iter();
      char cur;
      bool first = true;
      bool digit = false;
      while (iter.next().copy_if_present(cur)) {
        if (first) {
          first = false;
          if (cur == '+') {
            continue;
          }
        }
        if (!is_digit(cur)) {
          return false;
        }
        digit = true;
      }
      return digit;
    }

Here is the call graph for this function:

Here is the caller graph for this function:

unescape_char()

Result< char, UnescapeError > mtcore::ascii::unescape_char ( Slice< const char > str, char escapeChar = '\\' )

inline

Unescapes the first (potentially) escaped character in a character sequence If the sequence is empty, will return an error.

Parameters

str	String to unescape
escapeChar	Escape character

Returns

The unescaped character or an error

Definition at line 343 of file ascii.hpp.

                                                                                                    {
      if (str.empty()) {
        return error(UnescapeError::EMPTY_INPUT);
      }
 
      if (str.size() == 1) {
        if (str[0] == escapeChar) {
          return error(UnescapeError::EMPTY_INPUT);
        }
        return str[0];
      }
 
      if (str[0] != escapeChar) {
        return str[0];
      }
 
      char escaped = str[1];
      switch (str[1]) {
        case '0':
          escaped = '\0';
          break;
        case '?':
          escaped = '\?';
          break;
        case 'a':
          escaped = '\a';
          break;
        case 'b':
          escaped = '\b';
          break;
        case 'e':
          escaped = '\x1B';
          break;
        case 'f':
          escaped = '\f';
          break;
        case 'n':
          escaped = '\n';
          break;
        case 'r':
          escaped = '\r';
          break;
        case 't':
          escaped = '\t';
          break;
        case 'v':
          escaped = '\v';
          break;
        case 'x': {
          auto hex = std::array<char, 2>{'0', '0'};
          if (2 < str.size() && is_hex(str[2])) {
            hex[0] = str[2];
            if (3 < str.size() && is_hex(str[3])) {
              hex[1]        = str[3];
              auto parseRes = hex_to_int<char>(slice_from(hex));
              if (parseRes.is_success()) {
                escaped = parseRes.value();
              }
              else {
                return error(UnescapeError::INVALID_ESCAPE_SEQUENCE);
              }
            }
            else {
              return error(UnescapeError::INVALID_ESCAPE_SEQUENCE);
            }
          }
          else {
            return error(UnescapeError::INVALID_ESCAPE_SEQUENCE);
          }
          break;
        }
        default:
          escaped = str[1];
      }
      return escaped;
    }

Here is the call graph for this function:

Here is the caller graph for this function:

write_unescaped()

template<typename Writer>

Result< size_t, std::variant< typename Writer::ErrType, UnescapeError > > mtcore::ascii::write_unescaped	(	Writer &	writer,
		Slice< const char >	str,
		char	escapeChar = '\\' )

Writes unescaped ASCII characters to a stream Note: This does NOT support writing Unicode escape codes at this time (so \uhhhh or \Uhhhhhhhh)

Supported escape sequences (assuming escape character is \):

• \t tab
• 
  newline
• \r carriage return
• \0 null
• \f form feed
• alert/bell
• backspace
• escape character (0x1B)
• \v vertical tab
• \xhh hex character

All other escaped characters are that escaped character (e.g. \ => \, \{ => {)

Template Parameters

Writer

Writer type to write to

Parameters

writer	Writer to write to
str	String to write
escapeChar	Character to recognize as the escape character (default is '\')

Returns

Number of characters written

Definition at line 447 of file ascii.hpp.

                                                                                   {
      using ErrType  = std::variant<typename Writer::ErrType, UnescapeError>;
      size_t written = 0;
      for (size_t i = 0; i < str.size(); ++i) {
        auto cur = str[i];
        if (cur == escapeChar) {
          if (i + 1 < str.size()) {
            // we're going to consume at least one additional character
            mtdefer { i += 1; };
            char escaped = str[i + 1];
            switch (str[i + 1]) {
              case '0':
                escaped = '\0';
                break;
              case '?':
                escaped = '\?';
                break;
              case 'a':
                escaped = '\a';
                break;
              case 'b':
                escaped = '\b';
                break;
              case 'e':
                escaped = '\x1B';
                break;
              case 'f':
                escaped = '\f';
                break;
              case 'n':
                escaped = '\n';
                break;
              case 'r':
                escaped = '\r';
                break;
              case 't':
                escaped = '\t';
                break;
              case 'v':
                escaped = '\v';
                break;
              case 'x': {
                auto hex = std::array{'0', '0'};
                if (i + 2 < str.size() && is_hex(str[i + 2])) {
                  hex[0] = str[i + 2];
                  if (i + 3 < str.size() && is_hex(str[i + 3])) {
                    hex[1]        = str[i + 3];
                    auto parseRes = hex_to_int<char>(slice_from(hex));
                    if (parseRes.is_success()) {
                      mtdefer { i += 2; };
                      escaped = parseRes.value();
                    }
                    else {
                      return error(ErrType{UnescapeError::INVALID_ESCAPE_SEQUENCE});
                    }
                  }
                  else {
                    return error(ErrType{UnescapeError::INVALID_ESCAPE_SEQUENCE});
                  }
                }
                else {
                  return error(ErrType{UnescapeError::INVALID_ESCAPE_SEQUENCE});
                }
                break;
              }
              default:
                escaped = str[i + 1];
            }
 
            auto chRes = writer.write(escaped);
            if (chRes.is_error()) {
              return error(ErrType{chRes.error().code});
            }
            ++written;
          }
          else {
            return error(ErrType{UnescapeError::INVALID_ESCAPE_SEQUENCE});
          }
        }
        else {
          auto chRes = writer.write(cur);
          if (chRes.is_error()) {
            return error(ErrType{chRes.error().code});
          }
          ++written;
        }
      }
      return written;
    }

Here is the call graph for this function:

Here is the caller graph for this function: