Skip to content

Commit

Permalink
[Docs] Update docs for optional var in fn functions.
Browse files Browse the repository at this point in the history 
MODULAR_ORIG_COMMIT_REV_ID: e8aacb958bc13d386eb39840cdae30333ddca91b
  • Loading branch information
@arthurevans @modularbot
arthurevans authored and modularbot committed Sep 13, 2024
1 parent b75fc04 commit b979898
Show file tree
Hide file tree
Showing 2 changed files with 30 additions and 69 deletions.
8 changes: 1 addition & 7 deletions docs/manual/functions.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -93,9 +93,6 @@
" `inout` [argument\n",
" convention](/mojo/manual/values/ownership#argument-conventions)).\n",
"\n",
"- [Variables](/mojo/manual/variables) must be declared using the `var`\n",
" keyword.\n",
"\n",
"- If the function raises an exception, it must be explicitly declared with the\n",
" `raises` keyword. (A `def` function does not need to declare exceptions.)\n",
"\n",
Expand Down Expand Up @@ -174,10 +171,7 @@
" [object reference\n",
" semantics](/mojo/manual/values/value-semantics#python-style-reference-semantics).\n",
" \n",
" If an argument is any other declared type, it's received as a value.\n",
"\n",
"- [Variables](/mojo/manual/variables) don't need to be declared using \n",
" `var`."
" If an argument is any other declared type, it's received as a value."
]
},
{
Expand Down
91 changes: 29 additions & 62 deletions docs/manual/variables.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,15 +27,15 @@
"\n",
"Mojo has two kinds of variables:\n",
"\n",
"- Declared variables are created with the `var` keyword, and may include\n",
"- Explicitly-declared variables are created with the `var` keyword, and may include\n",
" [type annotations](#type-annotations).\n",
"\n",
" ```mojo\n",
" var a = 5\n",
" var b: Float64 = 3.14\n",
" ```\n",
" \n",
"- Undeclared variables are created with an assignment statement:\n",
"- Implicitly-declared variables are created with an assignment statement:\n",
"\n",
" ```mojo\n",
" a = 5\n",
Expand Down Expand Up @@ -87,10 +87,9 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"## Undeclared variables\n",
"## Implicitly-declared variables\n",
"\n",
"Within a `def` function or a REPL environment, you can create a variable with\n",
"just a name and a value. For example:"
"You can create a variable with just a name and a value. For example:"
]
},
{
Expand All @@ -99,49 +98,42 @@
"metadata": {},
"outputs": [],
"source": [
"name = str(\"Sam\")\n",
"name = String(\"Sam\")\n",
"user_id = 0"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Undeclared variables are strongly typed: they take the type from the first value\n",
"assigned to them. For example, the `user_id` variable above is type `Int`, while\n",
"the `name` variable is type `String`. You can't assign a string to `user_id` or an\n",
"integer to `name`. \n",
"\n",
"Undeclared variables are scoped at the function level. You create an undeclared\n",
"variable the first time you assign a value to a given name inside a function. \n",
"Any subsequent references to that name inside the function refer to the same\n",
"variable. For more information, see [Variable scopes](#variable-scopes), which\n",
"describes how variable scoping differs between declared and undeclared\n",
"variables.\n",
"\n",
":::note\n",
"\n",
"Undeclared variables are not allowed in an `fn` function or as a struct\n",
"field.\n",
"\n",
":::"
"Implicitly-declared variables are strongly typed: they take the type from the\n",
"first value assigned to them. For example, the `user_id` variable above is type\n",
"`Int`, while the `name` variable is type `String`. You can't assign a string to\n",
"`user_id` or an integer to `name`.\n",
"\n",
"Implicitly-declared variables are scoped at the function level. You create an\n",
"implicitly-declared variable the first time you assign a value to a given name\n",
"inside a function. Any subsequent references to that name inside the function\n",
"refer to the same variable. For more information, see [Variable\n",
"scopes](#variable-scopes), which describes how variable scoping differs between\n",
"explicitly- and implicitly-declared variables."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Declared variables\n",
"## Explicitly-declared variables\n",
"\n",
"You can declare a variable with the `var` keyword. For example:\n",
"\n",
"```mojo\n",
"var name = str(\"Sam\")\n",
"var name = String(\"Sam\")\n",
"var user_id: Int\n",
"```\n",
"The `name` variable is initialized to the string \"Sam\". The `user_id` variable \n",
"is uninitialized, but it has a declared type, `Int` for an integer value. All\n",
"declared values are typed—either explicitly with a \n",
"explicitly-declared variables are typed—either explicitly with a \n",
"[type annotation](#type-annotations) or implicitly when they're initialized with\n",
"a value.\n",
"\n",
Expand All @@ -154,43 +146,17 @@
"var user_id: Int = \"Sam\"\n",
"```\n",
"\n",
"There are several main differences between declared variables and undeclared\n",
"variables:\n",
"There are several main differences between explicitly-declared variables and\n",
"implicitly-declared variables:\n",
"\n",
"- A declared variable can be declared without initializing it:\n",
"- An explicitly-declared variable can be declared without initializing it:\n",
"\n",
" ```mojo\n",
" var value: Float64\n",
" ```\n",
"\n",
"- Declared variables follow [lexical scoping](#variable-scopes), unlike \n",
" undeclared variables.\n",
"\n",
"- Declared variables can be used in both `def` and `fn` functions.\n",
"\n",
"Using `var` can help prevent runtime errors caused by typos. For example,\n",
"if you misspell the name of an [undeclared variable](#undeclared-variables),\n",
"Mojo simply creates a new variable using the misspelled name. But when all\n",
"mutable variables must be first declared with `var` (which is the case inside\n",
"an `fn` function), then misspellings such as the following are caught by the\n",
"compiler:\n",
"\n",
"```mojo\n",
"var name = \"Sam\"\n",
"# Somewhere later...\n",
"name = \"Sammy\" # This is not allowed in an `fn` function\n",
"```\n",
"\n",
"Although you can use `var` in a `def` function, this benefit is\n",
"realized only when used inside an `fn` function, where the Mojo compiler will\n",
"flag undeclared variables (such as the above `nane`) as unknown declarations.\n",
"\n",
":::note\n",
"\n",
"When using Mojo in a REPL environment, top-level variables (variables\n",
"outside a function or struct) do not require `var` declarations.\n",
"\n",
":::"
"- Explicitly-declared variables follow [lexical scoping](#variable-scopes),\n",
" unlike implicitly-declared variables."
]
},
{
Expand Down Expand Up @@ -460,10 +426,11 @@
"The lifetime of the inner `num` ends exactly where the `if` code block ends,\n",
"because that's the scope in which the variable was defined.\n",
"\n",
"This is in contrast to undeclared variables (those without the `var`\n",
"This is in contrast to implicitly-declared variables (those without the `var`\n",
"keyword), which use **function-level scoping** (consistent with Python variable\n",
"behavior). That means, when you change the value of an undeclared variable\n",
"inside the `if` block, it actually changes the value for the entire function.\n",
"behavior). That means, when you change the value of an implicitly-declared\n",
"variable inside the `if` block, it actually changes the value for the entire\n",
"function.\n",
"\n",
"For example, here's the same code but *without* the `var` declarations:"
]
Expand Down Expand Up @@ -500,7 +467,7 @@
"metadata": {},
"source": [
"Now, the last `print()` function sees the updated `num` value from the inner\n",
"scope, because undeclared variables (Python-style variables) use function-level\n",
"scope, because implicitly-declared variables (Python-style variables) use function-level\n",
"scope (instead of lexical scope)."
]
}
Expand Down

0 comments on commit b979898

Please sign in to comment.