RtlUnicodeStringToInteger
TOC
Collapse the table of content
Expand the table of content

RtlUnicodeStringToInteger routine

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

Syntax


NTSTATUS RtlUnicodeStringToInteger(
  _In_     PCUNICODE_STRING String,
  _In_opt_ ULONG            Base,
  _Out_    PULONG           Value
);

Parameters

String [in]

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

Base [in, optional]

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.

Value [out]

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.

Input stringBaseOutput value
"123"10123
"  -345"10-345
"xyz"100
"   +678abc"10678
"   +678abc"166785724
"007"107
"789"87
"FGH"1615
"    "100

 

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

Requirements

Target platform

Universal

Version

Available starting with Windows 2000.

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)

Library

NtosKrnl.lib

DLL

NtosKrnl.exe

IRQL

PASSIVE_LEVEL

See also

RtlIntegerToUnicodeString
UNICODE_STRING

 

 

Send comments about this topic to Microsoft

Show:
© 2016 Microsoft