5 A block expression should have a newline after the initial `{` and before the
6 terminal `}`. Any qualifier before the block (e.g., `unsafe`) should always be
7 on the same line as the opening brace, and separated with a single space. The
8 contents of the block should be block indented:
15 a_call_inside_a_block();
17 // a comment in a block
24 a_call_inside_a_block();
26 // a comment in a block
31 fn unsafe_block_as_stmt() {
35 a_call_inside_a_block();
37 // a comment in a block
43 If a block has an attribute, it should be on its own line:
49 #![an_inner_attribute]
51 // a comment in a block
57 Avoid writing comments on the same line as the braces.
59 An empty block should be written as `{}`.
61 A block may be written on a single line if:
63 * it is either used in expression position (not statement position) or is an
64 unsafe block in statement position
65 * contains a single-line expression and no statements
66 * contains no comments
68 A single line block should have spaces after the opening brace and before the
77 let _ = unsafe { a_call() };
79 // Not allowed on one line
80 // Statement position.
85 // Contains a statement
119 Don't put any extra spaces before the first `|` (unless the closure is prefixed
120 by `move`); put a space between the second `|` and the expression of the
121 closure. Between the `|`s, you should use function definition syntax, however,
122 elide types where possible.
124 Use closures without the enclosing `{}`, if possible. Add the `{}` when you have
125 a return type, when there are statements, there are comments in the body, or the
126 body expression spans multiple lines and is a control-flow expression. If using
127 braces, follow the rules above for blocks. Examples:
132 move |arg1: i32, arg2: i32| -> i32 {
158 If a struct literal is *small* it may be formatted on a single line. If not,
159 each field should be on it's own, block-indented line. There should be a
160 trailing comma in the multi-line form only. There should be a space after the
163 There should be a space before the opening brace. In the single-line form there
164 should be spaces after the opening brace and before the closing brace.
167 Foo { field1, field2: 0 }
174 Functional record update syntax is treated like a field, but it must never have
175 a trailing comma. There should be no space after `..`.
185 Use a single-line form where possible. There should not be spaces around the
186 parentheses. Where a single-line form is not possible, each element of the tuple
187 should be on its own block-indented line and there should be a trailing comma.
194 another_very_long_expr,
199 ### Tuple struct literals
201 There should be no space between the identifier and the opening parenthesis.
202 Otherwise, follow the rules for tuple literals, e.g., `Foo(a, b)`.
207 Follow the formatting rules for the various struct literals. Prefer using the
208 name of the enum as a qualifying name, unless the enum is in the prelude. E.g.,
222 For simple array literals, avoid line breaking, no spaces around square
223 brackets, contents of the array should be separated by commas and spaces. If
224 using the repeating initialiser, there should be a space after the semicolon
225 only. Apply the same rules if using the `vec!` or similar macros (always use
226 square brackets here). Examples:
236 If a line must be broken, prefer breaking only after the `;`, if possible.
237 Otherwise, follow the rules below for function calls. In any case, the contents
238 of the initialiser should be block indented and there should be line breaks
239 after the opening bracket and before the closing bracket:
256 ### Array accesses, indexing, and slicing.
258 No spaces around the square brackets, avoid breaking lines if possible, never
259 break a line between the target expression and the opening bracket. If the
260 indexing expression covers multiple lines, then it should be block indented and
261 there should be newlines after the opening brackets and before the closing
262 bracket. However, this should be avoided where possible.
273 a_long_indexing_expression
280 Do not include a space between a unary op and its operand (i.e., `!x`, not
281 `! x`). However, there must be a space after `&mut`. Avoid line-breaking
282 between a unary operator and its operand.
284 ### Binary operations
286 Do include spaces around binary ops (i.e., `x + 1`, not `x+1`) (including `=`
287 and other assignment operators such as `+=` or `*=`).
289 For comparison operators, because for `T op U`, `&T op &U` is also implemented:
290 if you have `t: &T`, and `u: U`, prefer `*t op u` to `t op &u`. In general,
291 within expressions, prefer dereferencing to taking references.
293 Use parentheses liberally, do not necessarily elide them due to precedence.
294 Tools should not automatically insert or remove parentheses. Do not use spaces
295 to indicate precedence.
297 If line-breaking, put the operator on a new line and block indent. Put each
298 sub-expression on its own line. E.g.,
308 Prefer line-breaking at an assignment operator (either `=` or `+=`, etc.) rather
309 than at other binary operators.
313 Do not include extraneous parentheses for `if` and `while` expressions.
327 Do include extraneous parentheses if it makes an arithmetic or logic expression
328 easier to understand (`(x * 15) + (y * 20)` is fine)
332 Do not put a space between the function name, and the opening parenthesis.
334 Do not put a space between an argument, and the comma which follows.
336 Do put a space between an argument, and the comma which precedes it.
338 Prefer not to break a line in the callee expression.
340 #### Single-line calls
342 Do not put a space between the function name and open paren, between the open
343 paren and the first argument, or between the last argument and the close paren.
345 Do not put a comma after the last argument.
351 #### Multi-line calls
353 If the function call is not *small*, it would otherwise over-run the max width,
354 or any argument or the callee is multi-line, then the call should be formatted
355 across multiple lines. In this case, each argument should be on it's own block-
356 indented line, there should be a newline after the opening parenthesis and
357 before the closing parenthesis, and there should be a trailing comma. E.g.,
369 Follow the function rules for calling.
371 Do not put any spaces around the `.`.
374 x.foo().bar().baz(x, y, z);
380 Macros which can be parsed like other constructs should be formatted like those
381 constructs. For example, a macro use `foo!(a, b, c)` can be parsed like a
382 function call (ignoring the `!`), therefore it should be formatted following the
383 rules for function calls.
385 #### Special case macros
387 Macros which take a format string and where all other arguments are *small* may
388 be formatted with arguments before and after the format string on a single line
389 and the format string on its own line, rather than putting each argument on its
390 own line. For example,
400 "x and y were not equal, see {}",
408 Put spaces before and after `as`:
411 let cstr = "Hi\0" as *const str as *const [u8] as *const std::os::raw::c_char;
415 ### Chains of fields and method calls
417 A chain is a sequence of field accesses and/or method calls. A chain may also
418 include the try operator ('?'). E.g., `a.b.c().d` or `foo?.bar().baz?`.
420 Prefer formatting on one line if possible, and the chain is *small*. If
421 formatting on multiple lines, each field access or method call in the chain
422 should be on its own line with the line-break before the `.` and after any `?`.
423 Each line should be block-indented. E.g.,
431 If the length of the last line of the first element plus its indentation is
432 less than or equal to the indentation of the second line (and there is space),
433 then combine the first and second lines, e.g.,
450 #### Multi-line elements
452 If any element in a chain is formatted across multiple lines, then that element
453 and any later elements must be on their own line. Earlier elements may be kept
454 on a single line. E.g.,
466 Note there is block indent due to the chain and the function call in the above
469 Prefer formatting the whole chain in multi-line style and each element on one
470 line, rather than putting some elements on multiple lines and some on a single
477 .map_or(false, |comment| comment.starts_with("//"))
480 self.pre_comment.as_ref().map_or(
482 |comment| comment.starts_with("//"),
486 ### Control flow expressions
488 This section covers `if`, `if let`, `loop`, `while`, `while let`, and `for`
491 The keyword, any initial clauses, and the opening brace of the block should be
492 on a single line. The usual rules for [block formatting](#blocks) should be
493 applied to the block.
495 If there is an `else` component, then the closing brace, `else`, any following
496 clause, and the opening brace should all be on the same line. There should be a
497 single space before and after the `else` keyword. For example:
515 If the control line needs to be broken, then prefer to break before the `=` in
516 `* let` expressions and before `in` in a `for` expression; the following line
517 should be block indented. If the control line is broken for any reason, then the
518 opening brace should be on its own line and not indented. Examples:
534 && another_long_expression
535 || a_third_long_expression
541 Where the initial clause is multi-lined and ends with one or more closing
542 parentheses, square brackets, or braces, and there is nothing else on that line,
543 and that line is not indented beyond the indent on the first line of the control
544 flow expression, then the opening brace of the block should be put on the same
545 line with a preceding space. For example:
548 if !self.config.file_lines().intersects(
549 &self.codemap.lookup_line_range(
552 ) { // Opening brace on same line as initial clause.
558 #### Single line `if else`
560 Formatters may place an `if else` or `if let else` on a single line if it occurs
561 in expression context (i.e., is not a standalone statement), it contains a
562 single `else` clause, and is *small*. For example:
565 let y = if x { 0 } else { 1 };
567 // Examples that must be multi-line.
568 let y = if something_very_long {
584 Prefer not to line-break inside the discriminant expression. There must always
585 be a line break after the opening brace and before the closing brace. The match
586 arms must be block indented once:
593 let x = match foo.bar.baz() {
598 Use a trailing comma for a match arm if and only if not using a block.
600 Never start a match arm pattern with `|`, e.g.,
607 | a_very_long_pattern
609 | yet_another_pattern
610 | a_forth_pattern => {
624 | yet_another_pattern
625 | a_forth_pattern => {
631 Avoid splitting the left-hand side (before the `=>`) of a match arm where
632 possible. If the right-hand side of the match arm is kept on the same line,
633 never use a block (unless the block is empty).
635 If the right-hand side consists of multiple statements or has line comments or
636 the start of the line cannot be fit on the same line as the left-hand side, use
639 The body of a block arm should be block indented once.
646 a_very_long_patten | another_pattern if an_expression() => {
647 no_room_for_this_expression()
658 // Trailing comma on last item.
663 If the body is a single expression with no line comments and not a control flow
664 expression, then it may be started on the same line as the right-hand side. If
665 not, then it must be in a block. Example,
669 // A combinable expression.
670 foo => a_function_call(another_call(
674 // A non-combinable expression
689 Where it is possible to use a block form on the right-hand side and avoid
690 breaking the left-hand side, do that. E.g.
693 // Assuming the following line does done fit in the max width
694 a_very_long_pattern | another_pattern => ALongStructName {
698 a_very_long_pattern | another_pattern => {
703 // To splitting the pattern.
706 Never break after `=>` without using the block form of the body.
708 If the left-hand side must be split and there is an `if` clause, break before
709 the `if` and block indent. In this case, always use a block body and start the
713 a_very_long_pattern | another_pattern
720 If required to break the pattern, put each clause of the pattern on its own
721 line with no additional indent, breaking before the `|`. If there is an `if`
722 clause, then you must use the above form:
727 | yet_another_pattern
728 | a_forth_pattern => {
733 | yet_another_pattern
741 If the pattern is multi-line, and the last line is less wide than the indent, do
742 not put the `if` clause on a newline. E.g.,
749 } if num_context.is_ok(context.parsing_mode, value) => {
754 If every clause in a pattern is *small*, but does not fit on one line, then the
755 pattern may be formatted across multiple lines with as many clauses per line as
756 possible. Again break before a `|`:
765 We define a pattern clause to be *small* if it matches the following grammar:
770 - `&[single-line, ntp]`
774 - unary tuple constructor `([small, ntp])`
778 E.g., `&&Some(foo)` matches, `Foo(4, Bar)` does not.
781 ### Combinable expressions
783 Where a function call has a single argument, and that argument is formatted
784 across multiple-lines, the outer call may be formatted as if it were a single-
785 line call. The same combining behaviour may be applied to any similar
786 expressions which have multi-line, block-indented lists of sub-expressions
787 delimited by parentheses (e.g., macros or tuple struct literals). E.g.,
805 Such behaviour should extend recursively, however, tools may choose to limit the
808 Only where the multi-line sub-expression is a closure with an explicit block,
809 this combining behaviour may be used where there are other arguments, as long as
810 all the arguments and the first line of the closure fit on the first line, the
811 closure is the last argument, and there is only one closure argument:
814 foo(first_arg, x, |param| {
823 Do not put spaces in ranges, e.g., `0..10`, `x..=y`, `..x.len()`, `foo..`.
825 When writing a range with both upper and lower bounds, if the line must be
826 broken, break before the range operator and block indent the second line:
830 ..another_long_expression
833 For the sake of indicating precedence, we recommend that if either bound is a
834 compound expression, then use parentheses around it, e.g., `..(x + 1)`,
835 `(x.f)..(x.f.len())`, or `0..(x - 10)`.
838 ### Hexadecimal literals
840 Hexadecimal literals may use upper- or lower-case letters, but they must not be
841 mixed within the same literal. Projects should use the same case for all
842 literals, but we do not make a recommendation for either lower- or upper-case.
843 Tools should have an option to convert mixed case literals to upper-case, and
844 may have an option to convert all literals to either lower- or upper-case.
849 Patterns should be formatted like their corresponding expressions. See the
850 section on `match` for additional formatting for patterns in match arms.