diff options
| -rw-r--r-- | doc/classes/int.xml | 183 |
1 files changed, 88 insertions, 95 deletions
diff --git a/doc/classes/int.xml b/doc/classes/int.xml index 93fc8386c6..d5cb60e58d 100644 --- a/doc/classes/int.xml +++ b/doc/classes/int.xml @@ -1,40 +1,38 @@ <?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. + Built-in integer Variant 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. + Signed 64-bit integer type. This means that it can take values from [code]-2^63[/code] to [code]2^63 - 1[/code], i.e. from [code]-9223372036854775808[/code] to [code]9223372036854775807[/code]. When it exceeds these bounds, it will wrap around. + [int]s can be automatically converted to [float]s when necessary, for example when passing them as arguments in functions. The [float] will be as close to the original integer as possible. + Likewise, [float]s can be automatically converted into [int]s. This will truncate the [float], discarding anything after the floating point. + [b]Note:[/b] In a boolean context, an [int] will evaluate to [code]false[/code] if it equals [code]0[/code], and to [code]true[/code] otherwise. [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. + var x: int = 1 # x is 1 + x = 4.2 # x is 4, because 4.2 gets truncated + var max_int = 9223372036854775807 # Biggest value an int can store + max_int += 1 # max_int is -9223372036854775808, because it 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. + int x = 1; // x is 1 + x = 4.2; // x is 4, because 4.2 gets truncated + // We use long below, because GDScript's int is 64-bit while C#'s int is 32-bit. + long maxLong = 9223372036854775807; // Biggest value a long can store + maxLong++; // maxLong is now -9223372036854775808, because it 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. + // Alternatively with C#'s 32-bit int type, which has a smaller maximum value. + int maxInt = 2147483647; // Biggest value an int can store + maxInt++; // maxInt is now -2147483648, because it wrapped around [/csharp] [/codeblocks] + In GDScript, you can use the [code]0b[/code] literal for binary representation, the [code]0x[/code] literal for hexadecimal representation, and the [code]_[/code] symbol to separate long numbers and improve readability. + [codeblock] + var x = 0b1001 # x is 9 + var y = 0xF5 # y is 245 + var z = 10_000_000 # z is 10000000 + [/codeblock] </description> <tutorials> </tutorials> @@ -42,7 +40,7 @@ <constructor name="int"> <return type="int" /> <description> - Constructs a default-initialized [int] set to [code]0[/code]. + Constructs an [int] set to [code]0[/code]. </description> </constructor> <constructor name="int"> @@ -56,21 +54,21 @@ <return type="int" /> <param index="0" name="from" type="String" /> <description> - Converts a [String] to an [int], following the same rules as [method String.to_int]. + Constructs a new [int] from a [String], following the same rules as [method String.to_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. + Constructs a new [int] from a [bool]. [code]true[/code] is converted to [code]1[/code] and [code]false[/code] is converted to [code]0[/code]. </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. + Constructs a new [int] from a [float]. This will truncate the [float], discarding anything after the floating point. </description> </constructor> </constructors> @@ -79,25 +77,25 @@ <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]. + Returns [code]true[/code] if the [int] is not equivalent to the [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. + Returns [code]true[/code] if the [int]s 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. + Returns the remainder after dividing two [int]s. Uses truncated division, which returns a negative number if the dividend is negative. If this is not desired, consider using [method @GlobalScope.posmod]. [codeblock] - print(5 % 2) # 1 - print(12 % 4) # 0 - print(-5 % 3) # -2 + print(6 % 2) # Prints 0 + print(11 % 4) # Prints 3 + print(-5 % 3) # Prints -2 [/codeblock] </description> </operator> @@ -105,17 +103,16 @@ <return type="int" /> <param index="0" name="right" type="int" /> <description> - Returns the result of bitwise [code]AND[/code] operation for two integers. + Performs the bitwise [code]AND[/code] operation. [codeblock] - print(3 & 1) # 1 - print(11 & 3) # 3 + print(0b1100 & 0b1010) # Prints 8 (binary 1000) [/codeblock] - It's useful to retrieve binary flags from a variable. + This is useful for retrieving binary flags from a variable. [codeblock] - var flags = 5 - # Do something if the first bit is enabled. - if flags & 1: - do_stuff() + var flags = 0b101 + # Check if the first or second bit are enabled. + if flags & 0b011: + do_stuff() # This line will run. [/codeblock] </description> </operator> @@ -123,23 +120,23 @@ <return type="Color" /> <param index="0" name="right" type="Color" /> <description> - Multiplies each component of the [Color] by the given [int]. + Multiplies each component of the [Color] by the [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. + Multiplies each component of the [Quaternion] by the [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]. + Multiplies each component of the [Vector2] by the [int]. [codeblock] - print(2 * Vector2(1, 1)) # Vector2(2, 2) + print(2 * Vector2(1, 4)) # Prints (2, 8) [/codeblock] </description> </operator> @@ -147,49 +144,49 @@ <return type="Vector2i" /> <param index="0" name="right" type="Vector2i" /> <description> - Multiplies each component of the [Vector2i] by the given [int]. + Multiplies each component of the [Vector2i] by the [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]. + Multiplies each component of the [Vector3] by the [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]. + Multiplies each component of the [Vector3i] by the [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]. + Multiplies each component of the [Vector4] by the [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]. + Multiplies each component of the [Vector4i] by the [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]. + Multiplies the [float] by the [int]. 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. + Multiplies the two [int]s. </description> </operator> <operator name="operator **"> @@ -198,7 +195,7 @@ <description> Raises an [int] to a power of a [float]. The result is a [float]. [codeblock] - print(8**0.25) # 1.68179283050743 + print(2 ** 0.5) # Prints 1.4142135623731 [/codeblock] </description> </operator> @@ -206,9 +203,9 @@ <return type="int" /> <param index="0" name="right" type="int" /> <description> - Raises an [int] to a power of a [int]. + Raises the left [int] to a power of the right [int]. [codeblock] - print(5**5) # 3125 + print(3 ** 4) # Prints 81 [/codeblock] </description> </operator> @@ -216,37 +213,37 @@ <return type="float" /> <param index="0" name="right" type="float" /> <description> - Adds an [int] and a [float]. The result is a [float]. + Adds the [int] and the [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. + Adds the two [int]s. </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]. + Subtracts the [float] from the [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. + Subtracts the two [int]s. </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]. + Divides the [int] by the [float]. The result is a [float]. [codeblock] - print(10 / 3.0) # 3.333... + print(10 / 3.0) # Prints 3.33333333333333 [/codeblock] </description> </operator> @@ -254,10 +251,10 @@ <return type="int" /> <param index="0" name="right" type="int" /> <description> - Divides two integers. The decimal part of the result is discarded (truncated). + Divides the two [int]s. The result is an [int]. This will truncate the [float], discarding anything after the floating point. [codeblock] - print(10 / 2) # 5 - print(10 / 3) # 3 + print(6 / 2) # Prints 3 + print(5 / 3) # Prints 1 [/codeblock] </description> </operator> @@ -265,24 +262,24 @@ <return type="bool" /> <param index="0" name="right" type="float" /> <description> - Returns [code]true[/code] if this [int] is less than the given [float]. + Returns [code]true[/code] if the [int] is less than the [float]. </description> </operator> <operator name="operator <"> <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. + Returns [code]true[/code] if the left [int] is less than the right [int]. </description> </operator> <operator name="operator <<"> <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. + Performs the bitwise shift left operation. Effectively the same as multiplying by a power of 2. [codeblock] - print(10 << 1) # 20 - print(10 << 4) # 160 + print(0b1010 << 1) # Prints 20 (binary 10100) + print(0b1010 << 3) # Prints 80 (binary 1010000) [/codeblock] </description> </operator> @@ -290,66 +287,66 @@ <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]. + Returns [code]true[/code] if the [int] is less than or equal to the [float]. </description> </operator> <operator name="operator <="> <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. + Returns [code]true[/code] if the left [int] is less than or equal to the right [int]. </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]. + Returns [code]true[/code] if the [int] is equal to the [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. + Returns [code]true[/code] if the two [int]s are equal. </description> </operator> <operator name="operator >"> <return type="bool" /> <param index="0" name="right" type="float" /> <description> - Returns [code]true[/code] if this [int] is greater than the given [float]. + Returns [code]true[/code] if the [int] is greater than the [float]. </description> </operator> <operator name="operator >"> <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. + Returns [code]true[/code] if the left [int] is greater than the right [int]. </description> </operator> <operator name="operator >="> <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]. + Returns [code]true[/code] if the [int] is greater than or equal to the [float]. </description> </operator> <operator name="operator >="> <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. + Returns [code]true[/code] if the left [int] is greater than or equal to the right [int]. </description> </operator> <operator name="operator >>"> <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. + Performs the bitwise shift right operation. Effectively the same as dividing by a power of 2. [codeblock] - print(10 >> 1) # 5 - print(10 >> 2) # 2 + print(0b1010 >> 1) # Prints 5 (binary 101) + print(0b1010 >> 2) # Prints 2 (binary 10) [/codeblock] </description> </operator> @@ -357,10 +354,9 @@ <return type="int" /> <param index="0" name="right" type="int" /> <description> - Returns the result of bitwise [code]XOR[/code] operation for two integers. + Performs the bitwise [code]XOR[/code] operation. [codeblock] - print(5 ^ 1) # 4 - print(4 ^ 7) # 3 + print(0b1100 ^ 0b1010) # Prints 6 (binary 110) [/codeblock] </description> </operator> @@ -380,27 +376,24 @@ <return type="int" /> <param index="0" name="right" type="int" /> <description> - Returns the result of bitwise [code]OR[/code] operation for two integers. + Performs the bitwise [code]OR[/code] operation. [codeblock] - print(2 | 4) # 6 - print(1 | 3) # 3 + print(0b1100 | 0b1010) # Prints 14 (binary 1110) [/codeblock] - It's useful to store binary flags in a variable. + This is useful for storing binary flags in a variable. [codeblock] var flags = 0 - # Turn first and third bit on. - flags |= 1 - flags |= 4 + flags |= 0b101 # Turn the first and third bits on. [/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]. + Performs the bitwise [code]NOT[/code] operation on the [int]. Due to [url=https://en.wikipedia.org/wiki/Two%27s_complement/]2's complement[/url], it's effectively equal to [code]-(int + 1)[/code]. [codeblock] - print(~4) # -3 - print(~7) # -6 + print(~4) # Prints -5 + print(~(-7)) # Prints 6 [/codeblock] </description> </operator> |