path: root/doc/classes/int.xml

<?xml version="1.0" encoding="UTF-8" ?>
<class name="int" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
	<brief_description>
		Integer built-in type.
	</brief_description>
	<description>
		Signed 64-bit integer type.
		It can take values in the interval [code][-2^63, 2^63 - 1][/code], i.e. [code][-9223372036854775808, 9223372036854775807][/code]. Exceeding those bounds will wrap around.
		[int] is a [Variant] type, and will thus be used when assigning an integer value to a [Variant]. It can also be enforced with the [code]: int[/code] type hint.
		[codeblocks]
		[gdscript]
		var my_variant = 0 # int, value 0.
		my_variant += 4.2 # float, value 4.2.
		var my_int: int = 1 # int, value 1.
		my_int = 4.2 # int, value 4, the right value is implicitly cast to int.
		my_int = int("6.7") # int, value 6, the String is explicitly cast with int.
		var max_int = 9223372036854775807
		print(max_int) # 9223372036854775807, OK.
		max_int += 1
		print(max_int) # -9223372036854775808, we overflowed and wrapped around.
		[/gdscript]
		[csharp]
		int myInt = (int)"6.7".ToFloat(); // int, value 6, the String is explicitly cast with int.
		// We have to use `long` here, because GDSript's `int`
		// is 64 bits long while C#'s `int` is only 32 bits.
		long maxInt = 9223372036854775807;
		GD.Print(maxInt); // 9223372036854775807, OK.
		maxInt++;
		GD.Print(maxInt); // -9223372036854775808, we overflowed and wrapped around.

		// Alternatively, if we used C#'s 32-bit `int` type, the maximum value is much smaller:
		int halfInt = 2147483647;
		GD.Print(halfInt); // 2147483647, OK.
		halfInt++;
		GD.Print(halfInt); // -2147483648, we overflowed and wrapped around.
		[/csharp]
		[/codeblocks]
	</description>
	<tutorials>
	</tutorials>
	<constructors>
		<constructor name="int">
			<return type="int" />
			<description>
				Constructs a default-initialized [int] set to [code]0[/code].
			</description>
		</constructor>
		<constructor name="int">
			<return type="int" />
			<param index="0" name="from" type="int" />
			<description>
				Constructs an [int] as a copy of the given [int].
			</description>
		</constructor>
		<constructor name="int">
			<return type="int" />
			<param index="0" name="from" type="bool" />
			<description>
				Cast a [bool] value to an integer value, [code]int(true)[/code] will be equals to 1 and [code]int(false)[/code] will be equals to 0.
			</description>
		</constructor>
		<constructor name="int">
			<return type="int" />
			<param index="0" name="from" type="float" />
			<description>
				Cast a float value to an integer value, this method simply removes the number fractions (i.e. rounds [param from] towards zero), so for example [code]int(2.7)[/code] will be equals to 2, [code]int(0.1)[/code] will be equals to 0 and [code]int(-2.7)[/code] will be equals to -2. This operation is also called truncation.
			</description>
		</constructor>
	</constructors>
	<operators>
		<operator name="operator !=">
			<return type="bool" />
			<param index="0" name="right" type="float" />
			<description>
				Returns [code]true[/code] if this [int] is not equivalent to the given [float].
			</description>
		</operator>
		<operator name="operator !=">
			<return type="bool" />
			<param index="0" name="right" type="int" />
			<description>
				Returns [code]true[/code] if the integers are not equal.
			</description>
		</operator>
		<operator name="operator %">
			<return type="int" />
			<param index="0" name="right" type="int" />
			<description>
				Returns the remainder after dividing two integers. This operation uses truncated division, which is often not desired as it does not work well with negative numbers. Consider using [method @GlobalScope.posmod] instead if you want to handle negative numbers.
				[codeblock]
				print(5 % 2) # 1
				print(12 % 4) # 0
				print(-5 % 3) # -2
				[/codeblock]
			</description>
		</operator>
		<operator name="operator &amp;">
			<return type="int" />
			<param index="0" name="right" type="int" />
			<description>
				Returns the result of bitwise [code]AND[/code] operation for two integers.
				[codeblock]
				print(3 &amp; 1) # 1
				print(11 &amp; 3) # 3
				[/codeblock]
				It's useful to retrieve binary flags from a variable.
				[codeblock]
				var flags = 5
				# Do something if the first bit is enabled.
				if flags &amp; 1:
				    do_stuff()
				[/codeblock]
			</description>
		</operator>
		<operator name="operator *">
			<return type="Color" />
			<param index="0" name="right" type="Color" />
			<description>
				Multiplies each component of the [Color] by the given [int].
			</description>
		</operator>
		<operator name="operator *">
			<return type="Quaternion" />
			<param index="0" name="right" type="Quaternion" />
			<description>
				Multiplies each component of the [Quaternion] by the given [int]. This operation is not meaningful on its own, but it can be used as a part of a larger expression.
			</description>
		</operator>
		<operator name="operator *">
			<return type="Vector2" />
			<param index="0" name="right" type="Vector2" />
			<description>
				Multiplies each component of the [Vector2] by the given [int].
				[codeblock]
				print(2 * Vector2(1, 1)) # Vector2(2, 2)
				[/codeblock]
			</description>
		</operator>
		<operator name="operator *">
			<return type="Vector2i" />
			<param index="0" name="right" type="Vector2i" />
			<description>
				Multiplies each component of the [Vector2i] by the given [int].
			</description>
		</operator>
		<operator name="operator *">
			<return type="Vector3" />
			<param index="0" name="right" type="Vector3" />
			<description>
				Multiplies each component of the [Vector3] by the given [int].
			</description>
		</operator>
		<operator name="operator *">
			<return type="Vector3i" />
			<param index="0" name="right" type="Vector3i" />
			<description>
				Multiplies each component of the [Vector3i] by the given [int].
			</description>
		</operator>
		<operator name="operator *">
			<return type="Vector4" />
			<param index="0" name="right" type="Vector4" />
			<description>
				Multiplies each component of the [Vector4] by the given [int].
			</description>
		</operator>
		<operator name="operator *">
			<return type="Vector4i" />
			<param index="0" name="right" type="Vector4i" />
			<description>
				Multiplies each component of the [Vector4i] by the given [int].
			</description>
		</operator>
		<operator name="operator *">
			<return type="float" />
			<param index="0" name="right" type="float" />
			<description>
				Multiplies an [int] and a [float]. The result is a [float].
			</description>
		</operator>
		<operator name="operator *">
			<return type="int" />
			<param index="0" name="right" type="int" />
			<description>
				Multiplies two [int]s.
			</description>
		</operator>
		<operator name="operator **">
			<return type="float" />
			<param index="0" name="right" type="float" />
			<description>
				Raises an [int] to a power of a [float]. The result is a [float].
				[codeblock]
				print(8**0.25) # 1.68179283050743
				[/codeblock]
			</description>
		</operator>
		<operator name="operator **">
			<return type="int" />
			<param index="0" name="right" type="int" />
			<description>
				Raises an [int] to a power of a [int].
				[codeblock]
				print(5**5) # 3125
				[/codeblock]
			</description>
		</operator>
		<operator name="operator +">
			<return type="String" />
			<param index="0" name="right" type="String" />
			<description>
				Adds Unicode character with code [int] to the [String].
			</description>
		</operator>
		<operator name="operator +">
			<return type="float" />
			<param index="0" name="right" type="float" />
			<description>
				Adds an [int] and a [float]. The result is a [float].
			</description>
		</operator>
		<operator name="operator +">
			<return type="int" />
			<param index="0" name="right" type="int" />
			<description>
				Adds two integers.
			</description>
		</operator>
		<operator name="operator -">
			<return type="float" />
			<param index="0" name="right" type="float" />
			<description>
				Subtracts a [float] from an [int]. The result is a [float].
			</description>
		</operator>
		<operator name="operator -">
			<return type="int" />
			<param index="0" name="right" type="int" />
			<description>
				Subtracts two integers.
			</description>
		</operator>
		<operator name="operator /">
			<return type="float" />
			<param index="0" name="right" type="float" />
			<description>
				Divides an [int] by a [float]. The result is a [float].
				[codeblock]
				print(10 / 3.0) # 3.333...
				[/codeblock]
			</description>
		</operator>
		<operator name="operator /">
			<return type="int" />
			<param index="0" name="right" type="int" />
			<description>
				Divides two integers. The decimal part of the result is discarded (truncated).
				[codeblock]
				print(10 / 2) # 5
				print(10 / 3) # 3
				[/codeblock]
			</description>
		</operator>
		<operator name="operator &lt;">
			<return type="bool" />
			<param index="0" name="right" type="float" />
			<description>
				Returns [code]true[/code] if this [int] is less than the given [float].
			</description>
		</operator>
		<operator name="operator &lt;">
			<return type="bool" />
			<param index="0" name="right" type="int" />
			<description>
				Returns [code]true[/code] if the left integer is less than the right one.
			</description>
		</operator>
		<operator name="operator &lt;&lt;">
			<return type="int" />
			<param index="0" name="right" type="int" />
			<description>
				Performs bitwise shift left operation on the integer. Effectively the same as multiplying by a power of 2.
				[codeblock]
				print(10 &lt;&lt; 1) # 20
				print(10 &lt;&lt; 4) # 160
				[/codeblock]
			</description>
		</operator>
		<operator name="operator &lt;=">
			<return type="bool" />
			<param index="0" name="right" type="float" />
			<description>
				Returns [code]true[/code] if this [int] is less than or equal to the given [float].
			</description>
		</operator>
		<operator name="operator &lt;=">
			<return type="bool" />
			<param index="0" name="right" type="int" />
			<description>
				Returns [code]true[/code] if the left integer is less than or equal to the right one.
			</description>
		</operator>
		<operator name="operator ==">
			<return type="bool" />
			<param index="0" name="right" type="float" />
			<description>
				Returns [code]true[/code] if the integer is equal to the given [float].
			</description>
		</operator>
		<operator name="operator ==">
			<return type="bool" />
			<param index="0" name="right" type="int" />
			<description>
				Returns [code]true[/code] if both integers are equal.
			</description>
		</operator>
		<operator name="operator &gt;">
			<return type="bool" />
			<param index="0" name="right" type="float" />
			<description>
				Returns [code]true[/code] if this [int] is greater than the given [float].
			</description>
		</operator>
		<operator name="operator &gt;">
			<return type="bool" />
			<param index="0" name="right" type="int" />
			<description>
				Returns [code]true[/code] if the left integer is greater than the right one.
			</description>
		</operator>
		<operator name="operator &gt;=">
			<return type="bool" />
			<param index="0" name="right" type="float" />
			<description>
				Returns [code]true[/code] if this [int] is greater than or equal to the given [float].
			</description>
		</operator>
		<operator name="operator &gt;=">
			<return type="bool" />
			<param index="0" name="right" type="int" />
			<description>
				Returns [code]true[/code] if the left integer is greater than or equal to the right one.
			</description>
		</operator>
		<operator name="operator &gt;&gt;">
			<return type="int" />
			<param index="0" name="right" type="int" />
			<description>
				Performs bitwise shift right operation on the integer. Effectively the same as dividing by a power of 2.
				[codeblock]
				print(10 &gt;&gt; 1) # 5
				print(10 &gt;&gt; 2) # 2
				[/codeblock]
			</description>
		</operator>
		<operator name="operator ^">
			<return type="int" />
			<param index="0" name="right" type="int" />
			<description>
				Returns the result of bitwise [code]XOR[/code] operation for two integers.
				[codeblock]
				print(5 ^ 1) # 4
				print(4 ^ 7) # 3
				[/codeblock]
			</description>
		</operator>
		<operator name="operator unary+">
			<return type="int" />
			<description>
				Returns the same value as if the [code]+[/code] was not there. Unary [code]+[/code] does nothing, but sometimes it can make your code more readable.
			</description>
		</operator>
		<operator name="operator unary-">
			<return type="int" />
			<description>
				Returns the negated value of the [int]. If positive, turns the number negative. If negative, turns the number positive. If zero, does nothing.
			</description>
		</operator>
		<operator name="operator |">
			<return type="int" />
			<param index="0" name="right" type="int" />
			<description>
				Returns the result of bitwise [code]OR[/code] operation for two integers.
				[codeblock]
				print(2 | 4) # 6
				print(1 | 3) # 3
				[/codeblock]
				It's useful to store binary flags in a variable.
				[codeblock]
				var flags = 0
				# Turn first and third bit on.
				flags |= 1
				flags |= 4
				[/codeblock]
			</description>
		</operator>
		<operator name="operator ~">
			<return type="int" />
			<description>
				Returns the result of bitwise [code]NOT[/code] operation for the integer. It's effectively equal to [code]-int + 1[/code].
				[codeblock]
				print(~4) # -3
				print(~7) # -6
				[/codeblock]
			</description>
		</operator>
	</operators>
</class>