In this lecture, we'll get some more practice reading documentation. This is a critical skill for you to have as a game developer, as a programmer in general. I know no one says, I want to be a game developer so I can read documentation, but we just need to do this all the time. You'll be reading documentation throughout your programming life. Anytime you need to use code that's provided by somebody else, whether it's part of C-Sharp or whether it's part of the UD engine or it could even be code that I provide to you. You need to know how to read the documentation so you can figure out how to use the provided code and you just do this all the time. You'll practice and you'll get better at it, but this will be part of your programming life forever. Let's go solve a small problem that requires us to actually read and understand the documentation. I've already created a console app project called Reading Documentation, I added a documentation comment here and I added a documentation comment here and I added a line comment here saying calculate and print the cosine of 45 degrees. That's the problem we're trying to solve and we'll read some documentation to help us solve that problem. We're going to declare a variable to hold the cosine, now make it a float and I'll name it cosine. For now, I'll just give it a floating-point literal value because I want to show you something else about floating point literals. Let's say 0.8, which I know is incorrect. You'll see I've got some red squigglies there. I'm going to turn on the magnifier and the error message says literal of type double cannot be implicitly converted to type float, use an f suffix to create a literal of this type. When the compiler sees a literal number that has a decimal point in it, the compiler assumes that that's a double. We know because 2 to b equal n, we know that doubles can hold numbers with more precision than floats can so the compiler won't automatically take this potentially more precise number, and put it into a potentially less precise variable unless we say we really mean it and we do really mean it here. The error message said that we can use F as the suffix and we certainly can, though I'm going to use lowercase f. that works fine as well. Now we can get it to compile, we do have a warning here, those green squigglies are warnings. Red squigglies are errors, green squigglies are warnings and this warning just says that we have a variable that's assigned to, but we never use the value. Let's go ahead and use the value and I'll label the output in our concatenate cosine to it. Close parentheses and semicolon and when I run my code, we get 0.8, which is great we're encoding regard to number, but it's the wrong number. What we really need to do is we need to figure out how to actually calculate the cosine of an angle and here's where we actually go read documentation. As I said in the appendix of the book, I actually use local help regularly when I'm programming but I will use the online help for those of you who have just left the default and are using online help, we can get to the same documentation either way. Over here in the Microsoft documentation so docs.Microsoft.com in English, at least for me. Come down here and click C#, because we're doing C# programming, and up here in the search box, I'll just say cosine. I hit enter, and there are a variety of results here, and you can try to figure out which one makes the most sense. There are math functions in visual basic that really doesn't help us even though we said C#. There's a math class that we'll take a look at in a moment. But we actually have a math.cosine method that calculates the cosine. If we take a look at this documentation, we find a number of different things. I'm going to zoom in so we can see the details a little more clearly. We see a number of different things here. We see that the method is public, which is good. We'll learn about access modifiers later as we're building our own classes. But this basically says anybody outside the math class can actually call this method. I know I'm using this terminology we don't know yet. We haven't talked about classes yet. But we will soon, I promise. By soon, I mean next week. Just trust me, this is good that this is public because it means that we can use it. The next keyword we see is static, and we'll learn more about what static means next week as well. But this means when we call this method, we put the class name Math, with a capital M, before the method name. This is the return type for the method, so it returns a double. This is the method name, and it expects us to provide information to the method when we call it. Just like in Console.WriteLine, which also happens to be a static method. Just like in Console.WriteLine, we need to provide what we want to be output when we call Console.WriteLine, we need to provide here a parameter. It's called a perimeter here in the method, and we can look at the documentation for the parameters and see it says an angle. It says more than an angle, it will come back to this, but it says an angle, so we're in a hurry and we say, "Great, I need to give it an angle. Let's go do that." Let's go back to our code and we say, "Okay, static method." I put math. We put the name of the method we're trying to call, and we need to provide some information, and we want to provide 45 because we are trying to calculate the angle of 45-degree angle. Unfortunately, we're getting red squigglies and the error message is very similar to what we saw before. It says we can't convert type double to float, an explicit conversion exists. Are you missing a cast? The answer is, yes, we're missing a cast. We learned about typecasting when we needed to force division to be floating point division rather than integer division. Here, we need to cast the double that's returned from the Math cosine method into a float instead. The syntax for that typecast is the same as the syntax was before. This is how we typecast. Now we've typecast that return value from the method into a float. We run our code and we say, "Great, that's an awesome number. We must be right." One of the things that we really have to do in rewrite code is we need to know what the correct answer is. That's actually often called an expected result. When we run the code that behaves properly, we expect a particular result, and the expected result when we run this should be around 0.707. An important idea is you can't just run your code and get a number and say, "Awesome, I got a number, it must be correct." You have to actually know what the number should be to make sure you actually are getting the correct number. Let's go back to the documentation, as I said we would, and this time we'll read the documentation about that perimeter a little more carefully. We'll say, "Oh, it's an angled measured in radians and I'm passing in an angle measured in degrees." I know this needs to be converted to radians. You should know, or you could look up how to convert degrees to radians. Three hundred and sixty degrees is 2 Pi radians, so 180 degrees is Pi radians, and to make the units work out here, we need to multiply by, radians over degrees. You might say, well, I know what Pi is 3.1415, and I'll divide by 180. You can do this, it would compile and work fine, by the way, the compiler views this as a double, but that's okay. A double divided by an integer is a double, multiplied by an integer is a double, and the cosine method expects us to pass in a double. It's okay to pass in an int because ints are smaller than doubles, so it will automatically do that conversion. It's called an implicit type conversion, it will just do it because there's no danger of losing precision. We can pass in a float as well, but we can also pass in a double. There's a better answer here, than using 3.1415 though. Let's go back to the documentation to see that better answer. You have to believe that with all the Math people do with computers, that the Math class or some class, must provide us with a constant for Pi, rather than having people type in that magic number every time, there should be a constant provided, and there is. The way we can find it is over here on the left. Here in the Math class, we have a bunch of methods, and Pi is not a method. But we also have fields including Pi, and if we use the field Pi in the Math class, then we get 3.1415 and a bunch of other digits, so we get Pi to more decimal point precision, and we might as well just use this field. I will also point out that there is over hear, you may have noticed, there's also a MathF class that has fields and methods. If we know, we're only dealing with floats which we will regularly do, we would use the MathF class instead of the Math class. But I wanted to show you the typecasting and math have also, by the way, has Pi. Notice it's not to the same precision because, 2^b equal n, float constants can't store as wide a range of numbers as doubles can, so that's why this number here is shorter. Let's go back to our code and let's first use Math.Pi, and we'll run our code, and we get 0.707 n change, and that's the correct answer. As I said, I wanted to show you doing typecasting on a return value from a method, so I've shown you how we can do that. But since we're going to use exclusively floating point numbers in the courses in the specialization, let's actually use the MathF class instead. I'll get rid of this typecast. I'll change this to MathF with a capital F, I get a compilation error that tells me that argument one on the calling side of a method, the data that we pass in is called an argument, not a perimeter, so the first argument, the single argument we're providing, it says it can't convert from a double to a float because Math.Pi is in fact a double. We'll just use MathF.Pi instead, and when we run the code, we get 0.707 in change, which is good, and we've learned how to read documentation to help us solve a particular problem. To recap, in this lecture, we solved a pretty small problem, but we needed to read documentation to be able to solve that problem effectively.
