Static methods that help with common parsing jobs, such as parsing integers, floats, and strings with C escape sequences. More...

Source file:

/Core/Loyc.Syntax/Parsing/ParseHelpers.cs

Remarks

Static methods that help with common parsing jobs, such as parsing integers, floats, and strings with C escape sequences.

See also: PrintHelpers

Static Public Member Functions
static bool	TryParseHex (UString s, out int value)
	A simple method to parse a sequence of hex digits, without overflow checks or other features supported by methods like TryParseInt(string, ref int, out int, int, bool). More...

static int	TryParseHex (ref UString s, out int value)
	A simple method to parse a sequence of hex digits, without overflow checks or other features supported by methods like TryParseInt(string, ref int, out int, int, bool). More...

static int	HexDigitValue (char c)
	Gets the integer value for the specified hex digit, or -1 if the character is not a hex digit. More...

static int	Base36DigitValue (char c)
	Gets the integer value for the specified digit, where 'A' maps to 10 and 'Z' maps to 35, or -1 if the character is not a digit or letter. More...

static string	UnescapeCStyle (UString s, bool removeUnnecessaryBackslashes=false)
	Unescapes a string that uses C-style escape sequences, e.g. "\\\n\\\r" becomes "\n\r". More...

static StringBuilder	UnescapeCStyle (UString s, out EscapeC encountered, bool removeUnnecessaryBackslashes=false)
	Unescapes a string that uses C-style escape sequences, e.g. "\\\n\\\r" becomes "\n\r". More...

static int	UnescapeChar (string s, ref int i)

static int	UnescapeChar (ref UString s)

static int	UnescapeChar (ref UString s, ref EscapeC encountered)
	Unescapes a single character of a string. Returns the first character if it is not a backslash, or `</c> if it is a backslash but no escape sequence could be discerned.` More...

static bool	TryParseInt (string s, ref int index, out int result, int radix=10, bool skipSpaces=true)
	Tries to parse a string to an integer. Unlike Int32.TryParse(string, out int), this method allows parsing to start at any point in the string, it allows non-numeric data after the number, and it can parse numbers that are not in base 10. More...

static bool	TryParseInt (ref UString s, out int result, int radix=10, ParseNumberFlag flags=0)

static bool	TryParseInt (ref UString input, out long result, int radix=10, ParseNumberFlag flags=0)

static bool	TryParseUInt (ref UString s, out ulong result, int radix=10, ParseNumberFlag flags=0)
	Tries to parse a string to an unsigned integer. More...

static bool	TryParseUInt (ref UString s, out BigInteger result, int radix=10, ParseNumberFlag flags=0)

static bool	TryParseFloatParts (ref UString source, int radix, out bool negative, out ulong mantissa, out int exponentBaseR, out int exponentBase2, out int exponentBase10, out int numDigits, ParseNumberFlag flags=0)
	Low-level method that identifies the parts of a float literal of arbitrary base (typically base 2, 10, or 16) with no prefix or suffix, such as `2.Cp0` (which means 2.75 in base 16). More...

static bool	TryParseFloatParts (ref UString source, int radix, out bool negative, out ulong mantissa, out int exponentBase2, out int exponentBase10, out int numDigits, ParseNumberFlag flags=0)
	Parses the parts of a floating-point string. See the other overload for details. More...

static double	TryParseDouble (ref UString source, int radix, ParseNumberFlag flags=0)
	Parses a string to a double-precision float, returning NaN on failure or an infinity value on overflow. More...

static float	TryParseFloat (ref UString source, int radix, ParseNumberFlag flags=0)
	Parses a string to a single-precision float, returning NaN on failure or an infinity value on overflow. More...

static UString	SkipSpaces (UString s)
	Returns a string with any spaces and tabs removed from the beginning. More...

Member Function Documentation

◆ Base36DigitValue()

static int Loyc.Syntax.ParseHelpers.Base36DigitValue ( char c )

inlinestatic

Gets the integer value for the specified digit, where 'A' maps to 10 and 'Z' maps to 35, or -1 if the character is not a digit or letter.

◆ HexDigitValue()

static int Loyc.Syntax.ParseHelpers.HexDigitValue ( char c )

inlinestatic

Gets the integer value for the specified hex digit, or -1 if the character is not a hex digit.

Referenced by Loyc.Syntax.ParseHelpers.TryParseHex().

◆ SkipSpaces()

static UString Loyc.Syntax.ParseHelpers.SkipSpaces ( UString s )

inlinestatic

Returns a string with any spaces and tabs removed from the beginning.

Only ' ' and '\t' are treated as spaces.

References Loyc.UString.Substring().

Referenced by Loyc.Syntax.ParseHelpers.TryParseFloatParts(), and Loyc.Syntax.ParseHelpers.TryParseInt().

◆ TryParseDouble()

static double Loyc.Syntax.ParseHelpers.TryParseDouble	(	ref UString	source,
		int	radix,
		ParseNumberFlag	flags = `0`
	)

inlinestatic

Parses a string to a double-precision float, returning NaN on failure or an infinity value on overflow.

Parameters

radix	Base of the number to parse; must be 2 (binary), 4, 8 (octal), 10 (decimal), 16 (hexadecimal) or 32.
flags	Alters parsing behavior, see ParseNumberFlag.

References Loyc.Syntax.ParseHelpers.TryParseFloatParts().

◆ TryParseFloat()

static float Loyc.Syntax.ParseHelpers.TryParseFloat	(	ref UString	source,
		int	radix,
		ParseNumberFlag	flags = `0`
	)

inlinestatic

Parses a string to a single-precision float, returning NaN on failure or an infinity value on overflow.

Parameters

radix	Base of the number to parse; must be 2 (binary), 4, 8 (octal), 10 (decimal), 16 (hexadecimal) or 32.
flags	Alters parsing behavior, see ParseNumberFlag.

References Loyc.Syntax.ParseHelpers.TryParseFloatParts().

◆ TryParseFloatParts() [1/2]

static bool Loyc.Syntax.ParseHelpers.TryParseFloatParts	(	ref UString	source,
		int	radix,
		out bool	negative,
		out ulong	mantissa,
		out int	exponentBase2,
		out int	exponentBase10,
		out int	numDigits,
		ParseNumberFlag	flags = `0`
	)

inlinestatic

Parses the parts of a floating-point string. See the other overload for details.

Parameters

radix	Base of the number to parse; must be 2 (binary), 4, 8 (octal), 10 (decimal), 16 (hexadecimal) or 32.
negative	true if the string began with '-'.
mantissa	Integer magnitude of the number.
exponentBase2	Base-2 exponent to apply.
exponentBase10	Base-10 exponent to apply.
numDigits	Set to the number of digits in the number, not including the exponent part.
flags	Alters parsing behavior, see ParseNumberFlag.

This method is a wrapper around the other overload that combines the 'exponentBaseR' parameter with 'exponentBase2' or 'exponentBase10' depending on the radix. For example, when radix=10, this method adds exponentBaseR to exponentBase10.

References Loyc.G.Log2Floor(), and Loyc.Syntax.ParseHelpers.TryParseFloatParts().

◆ TryParseFloatParts() [2/2]

static bool Loyc.Syntax.ParseHelpers.TryParseFloatParts	(	ref UString	source,
		int	radix,
		out bool	negative,
		out ulong	mantissa,
		out int	exponentBaseR,
		out int	exponentBase2,
		out int	exponentBase10,
		out int	numDigits,
		ParseNumberFlag	flags = `0`
	)

inlinestatic

Low-level method that identifies the parts of a float literal of arbitrary base (typically base 2, 10, or 16) with no prefix or suffix, such as 2.Cp0 (which means 2.75 in base 16).

Parameters

radix	Base of the number to parse; must be between 2 and 36.
mantissa	Integer magnitude of the number.
exponentBase2	Base-2 exponent to apply, as specified by the 'p' suffix, or 0 if there is no 'p' suffix..
exponentBase10	Base-10 exponent to apply, as specified by the 'e' suffix, or 0 if there is no 'e' suffix..
exponentBaseR	Base-radix exponent to apply. This number is based on the front part of the number only (not including the 'p' or 'e' suffix). Negative values represent digits after the decimal point, while positive numbers represent 64-bit overflow. For example, if the input is `12.3456` with `radix=10`, the output will be `mantissa=123456` and `exponentBaseR=-4`. If the input is `0123_4567_89AB_CDEF_1234.5678` with `radix=16`, the mantissa overflows, and the result is `mantissa = 0x1234_5678_9ABC_DEF1` with `exponentBaseR=3`.
numDigits	Set to the number of digits in the number, not including the exponent part.
flags	Alters parsing behavior, see ParseNumberFlag.

The syntax required is

( '+'|'-' )?
( Digits ('.' Digits?)? | '.' Digits )
( ('p'|'P') ('-'|'+')? DecimalDigits+ )?
( ('e'|'E') ('-'|'+')? DecimalDigits+ )?

where Digits refers to one or more digits in the requested base, possibly including underscores or spaces if the flags allow it; similarly, DecimalDigits refers to base-10 digits and is also affected by the flags.

Returns false if there was an error interpreting the input.

To keep the parser relatively simple, it does not roll back in case of error the way the int parser does. For example, given the input "23p", the 'p' is consumed and causes the method to return false, even though the parse could have been successful if it had ignored the 'p'.

References Loyc.Syntax.ParseHelpers.SkipSpaces(), Loyc.Syntax.ParseHelpers.TryParseInt(), and Loyc.Syntax.ParseHelpers.TryParseUInt().

Referenced by Loyc.Syntax.ParseHelpers.TryParseDouble(), Loyc.Syntax.ParseHelpers.TryParseFloat(), and Loyc.Syntax.ParseHelpers.TryParseFloatParts().

◆ TryParseHex() [1/2]

static int Loyc.Syntax.ParseHelpers.TryParseHex	(	ref UString	s,
		out int	value
	)

inlinestatic

A simple method to parse a sequence of hex digits, without overflow checks or other features supported by methods like TryParseInt(string, ref int, out int, int, bool).

Returns: The number of digits parsed

References Loyc.Syntax.ParseHelpers.HexDigitValue().

◆ TryParseHex() [2/2]

static bool Loyc.Syntax.ParseHelpers.TryParseHex	(	UString	s,
		out int	value
	)

inlinestatic

A simple method to parse a sequence of hex digits, without overflow checks or other features supported by methods like TryParseInt(string, ref int, out int, int, bool).

Returns: true iff the entire string was consumed and the string was nonempty.

Referenced by Loyc.Syntax.ParseHelpers.UnescapeChar().

◆ TryParseInt()

static bool Loyc.Syntax.ParseHelpers.TryParseInt	(	string	s,
		ref int	index,
		out int	result,
		int	radix = `10`,
		bool	skipSpaces = `true`
	)

inlinestatic

Tries to parse a string to an integer. Unlike Int32.TryParse(string, out int), this method allows parsing to start at any point in the string, it allows non-numeric data after the number, and it can parse numbers that are not in base 10.

Parameters

radix	Number base, e.g. 10 for decimal and 2 for binary. Must be in the range 2 to 36.
index	Location at which to start parsing
flags	ParseNumberFlags that affect parsing behavior.
skipSpaces	Whether to skip spaces before parsing. Only the ' ' and '\t' characters are treated as spaces. No space is allowed between '-' and the digits of a negative number, even with this flag.

Returns: True if a number was found starting at the specified index and it was successfully converted to a number, or false if not.

This method never throws. If parsing fails, index is left unchanged, except that spaces are still skipped if you set the skipSpaces flag. If base>36, parsing can succeed but digits above 35 (Z) cannot occur in the output number. If the input number cannot fit in 'result', the return value is false but index increases anyway, and 'result' is a bitwise truncated version of the number.

When parsing input such as "12.34", the parser stops and returns true at the dot (with a result of 12 in this case).

References Loyc.UString.Slice().

Referenced by Loyc.Syntax.ParseHelpers.TryParseFloatParts(), and Loyc.Syntax.ParseHelpers.TryParseInt().

◆ TryParseUInt()

static bool Loyc.Syntax.ParseHelpers.TryParseUInt	(	ref UString	s,
		out ulong	result,
		int	radix = `10`,
		ParseNumberFlag	flags = `0`
	)

inlinestatic

Tries to parse a string to an unsigned integer.

Parameters

s	A slice of a string to be parsed.
radix	Number base, e.g. 10 for decimal and 2 for binary. Normally in the range 2 to 36.
flags	ParseNumberFlags that affect parsing behavior.

Returns: True if a number was found starting at the specified index and it was successfully converted to a number, or false if not.

This method never throws. It shrinks the slice s as it parses, so if parsing fails, s[0] will be the character at which parsing fails. If base>36, parsing can succeed but digits above 35 (Z) cannot be represented in the input string. If the number cannot fit in result, the return value is false and the method's exact behavior depends on whether you used ParseNumberFlag.StopBeforeOverflow.

When parsing input such as "12.34", the parser stops and returns true at the dot (with a result of 12 in this case).

Referenced by Loyc.Syntax.ParseHelpers.TryParseFloatParts(), Loyc.Syntax.ParseHelpers.TryParseInt(), and Loyc.Syntax.ParseHelpers.TryParseUInt().

◆ UnescapeChar()

static int Loyc.Syntax.ParseHelpers.UnescapeChar	(	ref UString	s,
		ref EscapeC	encountered
	)

inlinestatic

Unescapes a single character of a string. Returns the first character if it is not a backslash, or </c> if it is a backslash but no escape sequence could be discerned.

Parameters

s	Slice of a string to be unescaped. When using a `ref UString` overload of this method, `s` will be shorter upon returning from this method, as the parsed character(s) are clipped from the beginning (`s.InternalStart` is incremented by one normally and more than one in case of an escape sequence.)
encountered	Bits of this parameter are set according to which escape sequence is encountered, if any.

This function also decodes (non-escaped) surrogate pairs.

Code points with 5 or 6 digits such as \u1F4A9 are supported. \x escapes must be two digits and set the EscapeC.BackslashX flag. \u escapes must be 4 to 6 digits. If a \u escape has more than 4 digits, the EscapeC.HasLongEscapes flag is set. Invalid 6-digit escapes like \u123456 are "made valid" by being treated as 5 digits (the largest valid escape is \u10FFFF.)

Supported escapes: \u \x \ \r \0 \' " ` \t \f \v

EscapeC e = 0; UString str = "\nfoo"; char c = UnescapeChar(ref str, ref e); Contract.Assert(str == "foo"); Contract.Assert(e == EscapeC.HasEscapes);

References Loyc.UString.Left(), Loyc.UString.Substring(), and Loyc.Syntax.ParseHelpers.TryParseHex().

◆ UnescapeCStyle() [1/2]

static string Loyc.Syntax.ParseHelpers.UnescapeCStyle	(	UString	s,
		bool	removeUnnecessaryBackslashes = `false`
	)

inlinestatic

Unescapes a string that uses C-style escape sequences, e.g. "\\\n\\\r" becomes "\n\r".

◆ UnescapeCStyle() [2/2]

static StringBuilder Loyc.Syntax.ParseHelpers.UnescapeCStyle	(	UString	s,
		out EscapeC	encountered,
		bool	removeUnnecessaryBackslashes = `false`
	)

inlinestatic

Unescapes a string that uses C-style escape sequences, e.g. "\\\n\\\r" becomes "\n\r".

Parameters

encountered	Returns information about whether escape sequences were encountered, and which categories.
removeUnnecessaryBackslashes	Causes the backslash before an unrecognized escape sequence to be removed, e.g. "\z" => "z".

See UnescapeChar(ref UString, ref EscapeC) for details.

References Loyc.UString.Length.