RtlUnicodeStringToInteger function (wdm.h)

The RtlUnicodeStringToInteger routine converts a Unicode string representation of a number to the equivalent integer value.

Syntax

NTSYSAPI NTSTATUS RtlUnicodeStringToInteger(
  [in]           PCUNICODE_STRING String,
  [in, optional] ULONG            Base,
  [out]          PULONG           Value
);

Parameters

[in] String

A pointer to a UNICODE_STRING structure that contains the number representation to convert to the equivalent integer value.

[in, optional] Base

A numeric value that indicates the base (or radix) of the number that the Unicode string represents. This parameter value is optional and can be set to zero.

If Base is zero, RtlUnicodeStringToInteger checks the prefix of the Unicode string to determine the base of the number:

• If the prefix is "0x", RtlUnicodeStringToInteger interprets the number in the string as a hexadecimal integer.

• If the prefix is "0o", RtlUnicodeStringToInteger interprets the number in the string as an octal integer.

• If the prefix is "0b", RtlUnicodeStringToInteger interprets the number in the string as a binary integer.

If the Unicode string does not contain any of these prefixes, RtlUnicodeStringToInteger treats the string as a base-10 integer.

[out] Value

A pointer to a ULONG variable to which RtlUnicodeStringToInteger writes the integer value that results from conversion of the Unicode string.

Return value

If the conversion is successful, the RtlUnicodeStringToInteger routine returns STATUS_SUCCESS and sets *Value to the integer value represented by the number in the Unicode string. If the string is not empty, but does not start with a valid number representation, the routine returns STATUS_SUCCESS and sets *Value to zero. If the string is empty, the routine fails and returns STATUS_INVALID_PARAMETER.

Remarks

This routine skips any white space at the start of the input string to find the start of the number.

If the first non-white space character in the string is a hyphen (-), the integer value written to *Value is negative; otherwise, if the first character is a "+" or there is no sign character, the integer value written to *Value is positive.

If the string does not contain a valid number, or if the first digit in the string is preceded by a non-white space character other than '+' or '-', the routine sets the output value to zero and returns STATUS_SUCCESS.

A substring that contains one or more valid digits is terminated by any character that is not a valid digit. For example, if Base = 2, valid digits are '0' and '1'. If Base = 8, valid digits are '0' to '7'. If Base = 10, valid digits are '0' to '9'. If Base = 16, valid digits are '0' to '9', 'a' to 'f', and 'A' to 'F'.

The following table contains examples of output values that result from various combinations of input strings and Base parameter values.

A related routine, RtlIntegerToUnicodeString, converts an integer value to the equivalent Unicode string representation.

Requirements

See also

RtlIntegerToUnicodeString

UNICODE_STRING