<!DOCTYPE HTML>
<html lang="en" class="sidebar-visible no-js">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title></title>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#ffffff" />
<base href="">
<link rel="stylesheet" href="book.css">
<link href="https://fonts.googleapis.com/css?family=Open+Sans:300italic,400italic,600italic,700italic,800italic,400,300,600,700,800" rel="stylesheet" type="text/css">
<link href="https://fonts.googleapis.com/css?family=Source+Code+Pro:500" rel="stylesheet" type="text/css">
<link rel="shortcut icon" href="favicon.png">
<!-- Font Awesome -->
<link rel="stylesheet" href="_FontAwesome/css/font-awesome.css">
<link rel="stylesheet" href="highlight.css">
<link rel="stylesheet" href="tomorrow-night.css">
<link rel="stylesheet" href="ayu-highlight.css">
<!-- Custom theme stylesheets -->
</head>
<body class="light">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script type="text/javascript">
try {
var theme = localStorage.getItem('mdbook-theme');
var sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') && theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
</script>
<!-- Set the theme before any content is loaded, prevents flash -->
<script type="text/javascript">
var theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = 'light'; }
document.body.className = theme;
document.querySelector('html').className = theme + ' js';
</script>
<!-- Hide / unhide sidebar before it is displayed -->
<script type="text/javascript">
var html = document.querySelector('html');
var sidebar = 'hidden';
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
}
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<ol class="chapter"><li class="affix"><a href="the-unstable-book.html">The Unstable Book</a></li><li><a href="compiler-flags.html"><strong aria-hidden="true">1.</strong> Compiler flags</a></li><li><ol class="section"><li><a href="compiler-flags/linker-flavor.html"><strong aria-hidden="true">1.1.</strong> linker_flavor</a></li><li><a href="compiler-flags/profile.html"><strong aria-hidden="true">1.2.</strong> profile</a></li></ol></li><li><a href="language-features.html"><strong aria-hidden="true">2.</strong> Language features</a></li><li><ol class="section"><li><a href="language-features/aarch64-target-feature.html"><strong aria-hidden="true">2.1.</strong> aarch64_target_feature</a></li><li><a href="language-features/abi-msp430-interrupt.html"><strong aria-hidden="true">2.2.</strong> abi_msp430_interrupt</a></li><li><a href="language-features/abi-ptx.html"><strong aria-hidden="true">2.3.</strong> abi_ptx</a></li><li><a href="language-features/abi-thiscall.html"><strong aria-hidden="true">2.4.</strong> abi_thiscall</a></li><li><a href="language-features/abi-unadjusted.html"><strong aria-hidden="true">2.5.</strong> abi_unadjusted</a></li><li><a href="language-features/abi-vectorcall.html"><strong aria-hidden="true">2.6.</strong> abi_vectorcall</a></li><li><a href="language-features/abi-x86-interrupt.html"><strong aria-hidden="true">2.7.</strong> abi_x86_interrupt</a></li><li><a href="language-features/allocator-internals.html"><strong aria-hidden="true">2.8.</strong> allocator_internals</a></li><li><a href="language-features/allow-fail.html"><strong aria-hidden="true">2.9.</strong> allow_fail</a></li><li><a href="language-features/allow-internal-unsafe.html"><strong aria-hidden="true">2.10.</strong> allow_internal_unsafe</a></li><li><a href="language-features/allow-internal-unstable.html"><strong aria-hidden="true">2.11.</strong> allow_internal_unstable</a></li><li><a href="language-features/arbitrary-self-types.html"><strong aria-hidden="true">2.12.</strong> arbitrary_self_types</a></li><li><a href="language-features/arm-target-feature.html"><strong aria-hidden="true">2.13.</strong> arm_target_feature</a></li><li><a href="language-features/asm.html"><strong aria-hidden="true">2.14.</strong> asm</a></li><li><a href="language-features/associated-type-defaults.html"><strong aria-hidden="true">2.15.</strong> associated_type_defaults</a></li><li><a href="language-features/attr-literals.html"><strong aria-hidden="true">2.16.</strong> attr_literals</a></li><li><a href="language-features/avx512-target-feature.html"><strong aria-hidden="true">2.17.</strong> avx512_target_feature</a></li><li><a href="language-features/box-patterns.html"><strong aria-hidden="true">2.18.</strong> box_patterns</a></li><li><a href="language-features/box-syntax.html"><strong aria-hidden="true">2.19.</strong> box_syntax</a></li><li><a href="language-features/catch-expr.html"><strong aria-hidden="true">2.20.</strong> catch_expr</a></li><li><a href="language-features/cfg-target-has-atomic.html"><strong aria-hidden="true">2.21.</strong> cfg_target_has_atomic</a></li><li><a href="language-features/cfg-target-thread-local.html"><strong aria-hidden="true">2.22.</strong> cfg_target_thread_local</a></li><li><a href="language-features/cfg-target-vendor.html"><strong aria-hidden="true">2.23.</strong> cfg_target_vendor</a></li><li><a href="language-features/compiler-builtins.html"><strong aria-hidden="true">2.24.</strong> compiler_builtins</a></li><li><a href="language-features/concat-idents.html"><strong aria-hidden="true">2.25.</strong> concat_idents</a></li><li><a href="language-features/const-fn.html"><strong aria-hidden="true">2.26.</strong> const_fn</a></li><li><a href="language-features/const-let.html"><strong aria-hidden="true">2.27.</strong> const_let</a></li><li><a href="language-features/crate-in-paths.html"><strong aria-hidden="true">2.28.</strong> crate_in_paths</a></li><li><a href="language-features/crate-visibility-modifier.html"><strong aria-hidden="true">2.29.</strong> crate_visibility_modifier</a></li><li><a href="language-features/custom-attribute.html"><strong aria-hidden="true">2.30.</strong> custom_attribute</a></li><li><a href="language-features/custom-derive.html"><strong aria-hidden="true">2.31.</strong> custom_derive</a></li><li><a href="language-features/decl-macro.html"><strong aria-hidden="true">2.32.</strong> decl_macro</a></li><li><a href="language-features/default-type-parameter-fallback.html"><strong aria-hidden="true">2.33.</strong> default_type_parameter_fallback</a></li><li><a href="language-features/doc-alias.html"><strong aria-hidden="true">2.34.</strong> doc_alias</a></li><li><a href="language-features/doc-cfg.html"><strong aria-hidden="true">2.35.</strong> doc_cfg</a></li><li><a href="language-features/doc-keyword.html"><strong aria-hidden="true">2.36.</strong> doc_keyword</a></li><li><a href="language-features/doc-masked.html"><strong aria-hidden="true">2.37.</strong> doc_masked</a></li><li><a href="language-features/doc-spotlight.html"><strong aria-hidden="true">2.38.</strong> doc_spotlight</a></li><li><a href="language-features/dropck-eyepatch.html"><strong aria-hidden="true">2.39.</strong> dropck_eyepatch</a></li><li><a href="language-features/dropck-parametricity.html"><strong aria-hidden="true">2.40.</strong> dropck_parametricity</a></li><li><a href="language-features/exclusive-range-pattern.html"><strong aria-hidden="true">2.41.</strong> exclusive_range_pattern</a></li><li><a href="language-features/exhaustive-patterns.html"><strong aria-hidden="true">2.42.</strong> exhaustive_patterns</a></li><li><a href="language-features/extern-absolute-paths.html"><strong aria-hidden="true">2.43.</strong> extern_absolute_paths</a></li><li><a href="language-features/extern-in-paths.html"><strong aria-hidden="true">2.44.</strong> extern_in_paths</a></li><li><a href="language-features/extern-prelude.html"><strong aria-hidden="true">2.45.</strong> extern_prelude</a></li><li><a href="language-features/extern-types.html"><strong aria-hidden="true">2.46.</strong> extern_types</a></li><li><a href="language-features/external-doc.html"><strong aria-hidden="true">2.47.</strong> external_doc</a></li><li><a href="language-features/fundamental.html"><strong aria-hidden="true">2.48.</strong> fundamental</a></li><li><a href="language-features/generators.html"><strong aria-hidden="true">2.49.</strong> generators</a></li><li><a href="language-features/generic-associated-types.html"><strong aria-hidden="true">2.50.</strong> generic_associated_types</a></li><li><a href="language-features/global-asm.html"><strong aria-hidden="true">2.51.</strong> global_asm</a></li><li><a href="language-features/hexagon-target-feature.html"><strong aria-hidden="true">2.52.</strong> hexagon_target_feature</a></li><li><a href="language-features/if-while-or-patterns.html"><strong aria-hidden="true">2.53.</strong> if_while_or_patterns</a></li><li><a href="language-features/in-band-lifetimes.html"><strong aria-hidden="true">2.54.</strong> in_band_lifetimes</a></li><li><a href="language-features/infer-outlives-requirements.html"><strong aria-hidden="true">2.55.</strong> infer_outlives_requirements</a></li><li><a href="language-features/intrinsics.html"><strong aria-hidden="true">2.56.</strong> intrinsics</a></li><li><a href="language-features/label-break-value.html"><strong aria-hidden="true">2.57.</strong> label_break_value</a></li><li><a href="language-features/lang-items.html"><strong aria-hidden="true">2.58.</strong> lang_items</a></li><li><a href="language-features/link-args.html"><strong aria-hidden="true">2.59.</strong> link_args</a></li><li><a href="language-features/link-cfg.html"><strong aria-hidden="true">2.60.</strong> link_cfg</a></li><li><a href="language-features/link-llvm-intrinsics.html"><strong aria-hidden="true">2.61.</strong> link_llvm_intrinsics</a></li><li><a href="language-features/linkage.html"><strong aria-hidden="true">2.62.</strong> linkage</a></li><li><a href="language-features/log-syntax.html"><strong aria-hidden="true">2.63.</strong> log_syntax</a></li><li><a href="language-features/macro-at-most-once-rep.html"><strong aria-hidden="true">2.64.</strong> macro_at_most_once_rep</a></li><li><a href="language-features/macro-literal-matcher.html"><strong aria-hidden="true">2.65.</strong> macro_literal_matcher</a></li><li><a href="language-features/macro-vis-matcher.html"><strong aria-hidden="true">2.66.</strong> macro_vis_matcher</a></li><li><a href="language-features/macros-in-extern.html"><strong aria-hidden="true">2.67.</strong> macros_in_extern</a></li><li><a href="language-features/main.html"><strong aria-hidden="true">2.68.</strong> main</a></li><li><a href="language-features/mips-target-feature.html"><strong aria-hidden="true">2.69.</strong> mips_target_feature</a></li><li><a href="language-features/mmx-target-feature.html"><strong aria-hidden="true">2.70.</strong> mmx_target_feature</a></li><li><a href="language-features/naked-functions.html"><strong aria-hidden="true">2.71.</strong> naked_functions</a></li><li><a href="language-features/needs-allocator.html"><strong aria-hidden="true">2.72.</strong> needs_allocator</a></li><li><a href="language-features/needs-panic-runtime.html"><strong aria-hidden="true">2.73.</strong> needs_panic_runtime</a></li><li><a href="language-features/never-type.html"><strong aria-hidden="true">2.74.</strong> never_type</a></li><li><a href="language-features/nll.html"><strong aria-hidden="true">2.75.</strong> nll</a></li><li><a href="language-features/no-core.html"><strong aria-hidden="true">2.76.</strong> no_core</a></li><li><a href="language-features/no-debug.html"><strong aria-hidden="true">2.77.</strong> no_debug</a></li><li><a href="language-features/non-ascii-idents.html"><strong aria-hidden="true">2.78.</strong> non_ascii_idents</a></li><li><a href="language-features/non-exhaustive.html"><strong aria-hidden="true">2.79.</strong> non_exhaustive</a></li><li><a href="language-features/non-modrs-mods.html"><strong aria-hidden="true">2.80.</strong> non_modrs_mods</a></li><li><a href="language-features/omit-gdb-pretty-printer-section.html"><strong aria-hidden="true">2.81.</strong> omit_gdb_pretty_printer_section</a></li><li><a href="language-features/on-unimplemented.html"><strong aria-hidden="true">2.82.</strong> on_unimplemented</a></li><li><a href="language-features/optin-builtin-traits.html"><strong aria-hidden="true">2.83.</strong> optin_builtin_traits</a></li><li><a href="language-features/overlapping-marker-traits.html"><strong aria-hidden="true">2.84.</strong> overlapping_marker_traits</a></li><li><a href="language-features/panic-implementation.html"><strong aria-hidden="true">2.85.</strong> panic_implementation</a></li><li><a href="language-features/panic-runtime.html"><strong aria-hidden="true">2.86.</strong> panic_runtime</a></li><li><a href="language-features/pattern-parentheses.html"><strong aria-hidden="true">2.87.</strong> pattern_parentheses</a></li><li><a href="language-features/platform-intrinsics.html"><strong aria-hidden="true">2.88.</strong> platform_intrinsics</a></li><li><a href="language-features/plugin.html"><strong aria-hidden="true">2.89.</strong> plugin</a></li><li><a href="language-features/plugin-registrar.html"><strong aria-hidden="true">2.90.</strong> plugin_registrar</a></li><li><a href="language-features/powerpc-target-feature.html"><strong aria-hidden="true">2.91.</strong> powerpc_target_feature</a></li><li><a href="language-features/prelude-import.html"><strong aria-hidden="true">2.92.</strong> prelude_import</a></li><li><a href="language-features/proc-macro.html"><strong aria-hidden="true">2.93.</strong> proc_macro</a></li><li><a href="language-features/proc-macro-expr.html"><strong aria-hidden="true">2.94.</strong> proc_macro_expr</a></li><li><a href="language-features/proc-macro-gen.html"><strong aria-hidden="true">2.95.</strong> proc_macro_gen</a></li><li><a href="language-features/proc-macro-mod.html"><strong aria-hidden="true">2.96.</strong> proc_macro_mod</a></li><li><a href="language-features/proc-macro-non-items.html"><strong aria-hidden="true">2.97.</strong> proc_macro_non_items</a></li><li><a href="language-features/proc-macro-path-invoc.html"><strong aria-hidden="true">2.98.</strong> proc_macro_path_invoc</a></li><li><a href="language-features/profiler-runtime.html"><strong aria-hidden="true">2.99.</strong> profiler_runtime</a></li><li><a href="language-features/quote.html"><strong aria-hidden="true">2.100.</strong> quote</a></li><li><a href="language-features/raw-identifiers.html"><strong aria-hidden="true">2.101.</strong> raw_identifiers</a></li><li><a href="language-features/repr-packed.html"><strong aria-hidden="true">2.102.</strong> repr_packed</a></li><li><a href="language-features/repr-simd.html"><strong aria-hidden="true">2.103.</strong> repr_simd</a></li><li><a href="language-features/repr128.html"><strong aria-hidden="true">2.104.</strong> repr128</a></li><li><a href="language-features/rustc-attrs.html"><strong aria-hidden="true">2.105.</strong> rustc_attrs</a></li><li><a href="language-features/rustc-const-unstable.html"><strong aria-hidden="true">2.106.</strong> rustc_const_unstable</a></li><li><a href="language-features/rustc-diagnostic-macros.html"><strong aria-hidden="true">2.107.</strong> rustc_diagnostic_macros</a></li><li><a href="language-features/sanitizer-runtime.html"><strong aria-hidden="true">2.108.</strong> sanitizer_runtime</a></li><li><a href="language-features/simd-ffi.html"><strong aria-hidden="true">2.109.</strong> simd_ffi</a></li><li><a href="language-features/slice-patterns.html"><strong aria-hidden="true">2.110.</strong> slice_patterns</a></li><li><a href="language-features/specialization.html"><strong aria-hidden="true">2.111.</strong> specialization</a></li><li><a href="language-features/sse4a-target-feature.html"><strong aria-hidden="true">2.112.</strong> sse4a_target_feature</a></li><li><a href="language-features/staged-api.html"><strong aria-hidden="true">2.113.</strong> staged_api</a></li><li><a href="language-features/start.html"><strong aria-hidden="true">2.114.</strong> start</a></li><li><a href="language-features/static-nobundle.html"><strong aria-hidden="true">2.115.</strong> static_nobundle</a></li><li><a href="language-features/stmt-expr-attributes.html"><strong aria-hidden="true">2.116.</strong> stmt_expr_attributes</a></li><li><a href="language-features/structural-match.html"><strong aria-hidden="true">2.117.</strong> structural_match</a></li><li><a href="language-features/tbm-target-feature.html"><strong aria-hidden="true">2.118.</strong> tbm_target_feature</a></li><li><a href="language-features/thread-local.html"><strong aria-hidden="true">2.119.</strong> thread_local</a></li><li><a href="language-features/tool-attributes.html"><strong aria-hidden="true">2.120.</strong> tool_attributes</a></li><li><a href="language-features/trace-macros.html"><strong aria-hidden="true">2.121.</strong> trace_macros</a></li><li><a href="language-features/trait-alias.html"><strong aria-hidden="true">2.122.</strong> trait_alias</a></li><li><a href="language-features/trivial-bounds.html"><strong aria-hidden="true">2.123.</strong> trivial_bounds</a></li><li><a href="language-features/type-ascription.html"><strong aria-hidden="true">2.124.</strong> type_ascription</a></li><li><a href="language-features/unboxed-closures.html"><strong aria-hidden="true">2.125.</strong> unboxed_closures</a></li><li><a href="language-features/underscore-imports.html"><strong aria-hidden="true">2.126.</strong> underscore_imports</a></li><li><a href="language-features/unsized-tuple-coercion.html"><strong aria-hidden="true">2.127.</strong> unsized_tuple_coercion</a></li><li><a href="language-features/untagged-unions.html"><strong aria-hidden="true">2.128.</strong> untagged_unions</a></li><li><a href="language-features/unwind-attributes.html"><strong aria-hidden="true">2.129.</strong> unwind_attributes</a></li><li><a href="language-features/use-extern-macros.html"><strong aria-hidden="true">2.130.</strong> use_extern_macros</a></li><li><a href="language-features/used.html"><strong aria-hidden="true">2.131.</strong> used</a></li><li><a href="language-features/wasm-custom-section.html"><strong aria-hidden="true">2.132.</strong> wasm_custom_section</a></li><li><a href="language-features/wasm-import-module.html"><strong aria-hidden="true">2.133.</strong> wasm_import_module</a></li></ol></li><li><a href="library-features.html"><strong aria-hidden="true">3.</strong> Library Features</a></li><li><ol class="section"><li><a href="library-features/align-offset.html"><strong aria-hidden="true">3.1.</strong> align_offset</a></li><li><a href="library-features/alloc.html"><strong aria-hidden="true">3.2.</strong> alloc</a></li><li><a href="library-features/alloc-error-hook.html"><strong aria-hidden="true">3.3.</strong> alloc_error_hook</a></li><li><a href="library-features/alloc-internals.html"><strong aria-hidden="true">3.4.</strong> alloc_internals</a></li><li><a href="library-features/alloc-jemalloc.html"><strong aria-hidden="true">3.5.</strong> alloc_jemalloc</a></li><li><a href="library-features/alloc-system.html"><strong aria-hidden="true">3.6.</strong> alloc_system</a></li><li><a href="library-features/allocator-api.html"><strong aria-hidden="true">3.7.</strong> allocator_api</a></li><li><a href="library-features/array-error-internals.html"><strong aria-hidden="true">3.8.</strong> array_error_internals</a></li><li><a href="library-features/ascii-ctype.html"><strong aria-hidden="true">3.9.</strong> ascii_ctype</a></li><li><a href="library-features/atomic-min-max.html"><strong aria-hidden="true">3.10.</strong> atomic_min_max</a></li><li><a href="library-features/box-into-raw-non-null.html"><strong aria-hidden="true">3.11.</strong> box_into_raw_non_null</a></li><li><a href="library-features/bufreader-buffer.html"><strong aria-hidden="true">3.12.</strong> bufreader_buffer</a></li><li><a href="library-features/bufreader-is-empty.html"><strong aria-hidden="true">3.13.</strong> bufreader_is_empty</a></li><li><a href="library-features/bufreader-seek-relative.html"><strong aria-hidden="true">3.14.</strong> bufreader_seek_relative</a></li><li><a href="library-features/c-void-variant.html"><strong aria-hidden="true">3.15.</strong> c_void_variant</a></li><li><a href="library-features/cell-update.html"><strong aria-hidden="true">3.16.</strong> cell_update</a></li><li><a href="library-features/char-error-internals.html"><strong aria-hidden="true">3.17.</strong> char_error_internals</a></li><li><a href="library-features/coerce-unsized.html"><strong aria-hidden="true">3.18.</strong> coerce_unsized</a></li><li><a href="library-features/compiler-builtins-lib.html"><strong aria-hidden="true">3.19.</strong> compiler_builtins_lib</a></li><li><a href="library-features/concat-idents-macro.html"><strong aria-hidden="true">3.20.</strong> concat_idents_macro</a></li><li><a href="library-features/const-int-ops.html"><strong aria-hidden="true">3.21.</strong> const_int_ops</a></li><li><a href="library-features/const-manually-drop-new.html"><strong aria-hidden="true">3.22.</strong> const_manually_drop_new</a></li><li><a href="library-features/const-slice-as-ptr.html"><strong aria-hidden="true">3.23.</strong> const_slice_as_ptr</a></li><li><a href="library-features/const-slice-len.html"><strong aria-hidden="true">3.24.</strong> const_slice_len</a></li><li><a href="library-features/const-str-as-bytes.html"><strong aria-hidden="true">3.25.</strong> const_str_as_bytes</a></li><li><a href="library-features/const-str-as-ptr.html"><strong aria-hidden="true">3.26.</strong> const_str_as_ptr</a></li><li><a href="library-features/const-str-len.html"><strong aria-hidden="true">3.27.</strong> const_str_len</a></li><li><a href="library-features/const-string-new.html"><strong aria-hidden="true">3.28.</strong> const_string_new</a></li><li><a href="library-features/const-type-id.html"><strong aria-hidden="true">3.29.</strong> const_type_id</a></li><li><a href="library-features/const-vec-new.html"><strong aria-hidden="true">3.30.</strong> const_vec_new</a></li><li><a href="library-features/core-intrinsics.html"><strong aria-hidden="true">3.31.</strong> core_intrinsics</a></li><li><a href="library-features/core-panic.html"><strong aria-hidden="true">3.32.</strong> core_panic</a></li><li><a href="library-features/core-panic-info.html"><strong aria-hidden="true">3.33.</strong> core_panic_info</a></li><li><a href="library-features/core-private-bignum.html"><strong aria-hidden="true">3.34.</strong> core_private_bignum</a></li><li><a href="library-features/core-private-diy-float.html"><strong aria-hidden="true">3.35.</strong> core_private_diy_float</a></li><li><a href="library-features/deadline-api.html"><strong aria-hidden="true">3.36.</strong> deadline_api</a></li><li><a href="library-features/dec2flt.html"><strong aria-hidden="true">3.37.</strong> dec2flt</a></li><li><a href="library-features/decode-utf8.html"><strong aria-hidden="true">3.38.</strong> decode_utf8</a></li><li><a href="library-features/derive-clone-copy.html"><strong aria-hidden="true">3.39.</strong> derive_clone_copy</a></li><li><a href="library-features/derive-eq.html"><strong aria-hidden="true">3.40.</strong> derive_eq</a></li><li><a href="library-features/drain-filter.html"><strong aria-hidden="true">3.41.</strong> drain_filter</a></li><li><a href="library-features/duration-as-u128.html"><strong aria-hidden="true">3.42.</strong> duration_as_u128</a></li><li><a href="library-features/duration-getters.html"><strong aria-hidden="true">3.43.</strong> duration_getters</a></li><li><a href="library-features/error-type-id.html"><strong aria-hidden="true">3.44.</strong> error_type_id</a></li><li><a href="library-features/euclidean-division.html"><strong aria-hidden="true">3.45.</strong> euclidean_division</a></li><li><a href="library-features/exact-chunks.html"><strong aria-hidden="true">3.46.</strong> exact_chunks</a></li><li><a href="library-features/exact-size-is-empty.html"><strong aria-hidden="true">3.47.</strong> exact_size_is_empty</a></li><li><a href="library-features/extra-log-consts.html"><strong aria-hidden="true">3.48.</strong> extra_log_consts</a></li><li><a href="library-features/fd.html"><strong aria-hidden="true">3.49.</strong> fd</a></li><li><a href="library-features/fd-read.html"><strong aria-hidden="true">3.50.</strong> fd_read</a></li><li><a href="library-features/fixed-size-array.html"><strong aria-hidden="true">3.51.</strong> fixed_size_array</a></li><li><a href="library-features/flt2dec.html"><strong aria-hidden="true">3.52.</strong> flt2dec</a></li><li><a href="library-features/fmt-internals.html"><strong aria-hidden="true">3.53.</strong> fmt_internals</a></li><li><a href="library-features/fn-traits.html"><strong aria-hidden="true">3.54.</strong> fn_traits</a></li><li><a href="library-features/fnbox.html"><strong aria-hidden="true">3.55.</strong> fnbox</a></li><li><a href="library-features/future-atomic-orderings.html"><strong aria-hidden="true">3.56.</strong> future_atomic_orderings</a></li><li><a href="library-features/futures-api.html"><strong aria-hidden="true">3.57.</strong> futures_api</a></li><li><a href="library-features/generator-trait.html"><strong aria-hidden="true">3.58.</strong> generator_trait</a></li><li><a href="library-features/get-type-id.html"><strong aria-hidden="true">3.59.</strong> get_type_id</a></li><li><a href="library-features/hashmap-internals.html"><strong aria-hidden="true">3.60.</strong> hashmap_internals</a></li><li><a href="library-features/int-error-internals.html"><strong aria-hidden="true">3.61.</strong> int_error_internals</a></li><li><a href="library-features/int-to-from-bytes.html"><strong aria-hidden="true">3.62.</strong> int_to_from_bytes</a></li><li><a href="library-features/integer-atomics.html"><strong aria-hidden="true">3.63.</strong> integer_atomics</a></li><li><a href="library-features/io.html"><strong aria-hidden="true">3.64.</strong> io</a></li><li><a href="library-features/io-error-internals.html"><strong aria-hidden="true">3.65.</strong> io_error_internals</a></li><li><a href="library-features/ip.html"><strong aria-hidden="true">3.66.</strong> ip</a></li><li><a href="library-features/ip-constructors.html"><strong aria-hidden="true">3.67.</strong> ip_constructors</a></li><li><a href="library-features/iterator-find-map.html"><strong aria-hidden="true">3.68.</strong> iterator_find_map</a></li><li><a href="library-features/iterator-flatten.html"><strong aria-hidden="true">3.69.</strong> iterator_flatten</a></li><li><a href="library-features/libstd-io-internals.html"><strong aria-hidden="true">3.70.</strong> libstd_io_internals</a></li><li><a href="library-features/libstd-sys-internals.html"><strong aria-hidden="true">3.71.</strong> libstd_sys_internals</a></li><li><a href="library-features/libstd-thread-internals.html"><strong aria-hidden="true">3.72.</strong> libstd_thread_internals</a></li><li><a href="library-features/linked-list-extras.html"><strong aria-hidden="true">3.73.</strong> linked_list_extras</a></li><li><a href="library-features/map-entry-replace.html"><strong aria-hidden="true">3.74.</strong> map_entry_replace</a></li><li><a href="library-features/map-get-key-value.html"><strong aria-hidden="true">3.75.</strong> map_get_key_value</a></li><li><a href="library-features/mpsc-select.html"><strong aria-hidden="true">3.76.</strong> mpsc_select</a></li><li><a href="library-features/n16.html"><strong aria-hidden="true">3.77.</strong> n16</a></li><li><a href="library-features/no-more-cas.html"><strong aria-hidden="true">3.78.</strong> no_more_cas</a></li><li><a href="library-features/no-panic-pow.html"><strong aria-hidden="true">3.79.</strong> no_panic_pow</a></li><li><a href="library-features/offset-to.html"><strong aria-hidden="true">3.80.</strong> offset_to</a></li><li><a href="library-features/once-poison.html"><strong aria-hidden="true">3.81.</strong> once_poison</a></li><li><a href="library-features/option-xor.html"><strong aria-hidden="true">3.82.</strong> option_xor</a></li><li><a href="library-features/panic-abort.html"><strong aria-hidden="true">3.83.</strong> panic_abort</a></li><li><a href="library-features/panic-info-message.html"><strong aria-hidden="true">3.84.</strong> panic_info_message</a></li><li><a href="library-features/panic-internals.html"><strong aria-hidden="true">3.85.</strong> panic_internals</a></li><li><a href="library-features/panic-unwind.html"><strong aria-hidden="true">3.86.</strong> panic_unwind</a></li><li><a href="library-features/pattern.html"><strong aria-hidden="true">3.87.</strong> pattern</a></li><li><a href="library-features/pin.html"><strong aria-hidden="true">3.88.</strong> pin</a></li><li><a href="library-features/print-internals.html"><strong aria-hidden="true">3.89.</strong> print_internals</a></li><li><a href="library-features/proc-macro-internals.html"><strong aria-hidden="true">3.90.</strong> proc_macro_internals</a></li><li><a href="library-features/process-exitcode-placeholder.html"><strong aria-hidden="true">3.91.</strong> process_exitcode_placeholder</a></li><li><a href="library-features/process-internals.html"><strong aria-hidden="true">3.92.</strong> process_internals</a></li><li><a href="library-features/profiler-runtime-lib.html"><strong aria-hidden="true">3.93.</strong> profiler_runtime_lib</a></li><li><a href="library-features/ptr-internals.html"><strong aria-hidden="true">3.94.</strong> ptr_internals</a></li><li><a href="library-features/ptr-offset-from.html"><strong aria-hidden="true">3.95.</strong> ptr_offset_from</a></li><li><a href="library-features/ptr-wrapping-offset-from.html"><strong aria-hidden="true">3.96.</strong> ptr_wrapping_offset_from</a></li><li><a href="library-features/range-contains.html"><strong aria-hidden="true">3.97.</strong> range_contains</a></li><li><a href="library-features/range-is-empty.html"><strong aria-hidden="true">3.98.</strong> range_is_empty</a></li><li><a href="library-features/raw.html"><strong aria-hidden="true">3.99.</strong> raw</a></li><li><a href="library-features/rc-downcast.html"><strong aria-hidden="true">3.100.</strong> rc_downcast</a></li><li><a href="library-features/read-initializer.html"><strong aria-hidden="true">3.101.</strong> read_initializer</a></li><li><a href="library-features/refcell-map-split.html"><strong aria-hidden="true">3.102.</strong> refcell_map_split</a></li><li><a href="library-features/refcell-replace-swap.html"><strong aria-hidden="true">3.103.</strong> refcell_replace_swap</a></li><li><a href="library-features/repeat-generic-slice.html"><strong aria-hidden="true">3.104.</strong> repeat_generic_slice</a></li><li><a href="library-features/reverse-bits.html"><strong aria-hidden="true">3.105.</strong> reverse_bits</a></li><li><a href="library-features/rt.html"><strong aria-hidden="true">3.106.</strong> rt</a></li><li><a href="library-features/rustc-private.html"><strong aria-hidden="true">3.107.</strong> rustc_private</a></li><li><a href="library-features/rustc-stack-internals.html"><strong aria-hidden="true">3.108.</strong> rustc_stack_internals</a></li><li><a href="library-features/sanitizer-runtime-lib.html"><strong aria-hidden="true">3.109.</strong> sanitizer_runtime_lib</a></li><li><a href="library-features/set-stdio.html"><strong aria-hidden="true">3.110.</strong> set_stdio</a></li><li><a href="library-features/shrink-to.html"><strong aria-hidden="true">3.111.</strong> shrink_to</a></li><li><a href="library-features/slice-align-to.html"><strong aria-hidden="true">3.112.</strong> slice_align_to</a></li><li><a href="library-features/slice-concat-ext.html"><strong aria-hidden="true">3.113.</strong> slice_concat_ext</a></li><li><a href="library-features/slice-index-methods.html"><strong aria-hidden="true">3.114.</strong> slice_index_methods</a></li><li><a href="library-features/slice-internals.html"><strong aria-hidden="true">3.115.</strong> slice_internals</a></li><li><a href="library-features/slice-sort-by-cached-key.html"><strong aria-hidden="true">3.116.</strong> slice_sort_by_cached_key</a></li><li><a href="library-features/sort-internals.html"><strong aria-hidden="true">3.117.</strong> sort_internals</a></li><li><a href="library-features/std-internals.html"><strong aria-hidden="true">3.118.</strong> std_internals</a></li><li><a href="library-features/stdsimd.html"><strong aria-hidden="true">3.119.</strong> stdsimd</a></li><li><a href="library-features/step-trait.html"><strong aria-hidden="true">3.120.</strong> step_trait</a></li><li><a href="library-features/str-escape.html"><strong aria-hidden="true">3.121.</strong> str_escape</a></li><li><a href="library-features/str-internals.html"><strong aria-hidden="true">3.122.</strong> str_internals</a></li><li><a href="library-features/termination-trait-lib.html"><strong aria-hidden="true">3.123.</strong> termination_trait_lib</a></li><li><a href="library-features/test.html"><strong aria-hidden="true">3.124.</strong> test</a></li><li><a href="library-features/thread-local-internals.html"><strong aria-hidden="true">3.125.</strong> thread_local_internals</a></li><li><a href="library-features/toowned-clone-into.html"><strong aria-hidden="true">3.126.</strong> toowned_clone_into</a></li><li><a href="library-features/transpose-result.html"><strong aria-hidden="true">3.127.</strong> transpose_result</a></li><li><a href="library-features/trusted-len.html"><strong aria-hidden="true">3.128.</strong> trusted_len</a></li><li><a href="library-features/try-from.html"><strong aria-hidden="true">3.129.</strong> try_from</a></li><li><a href="library-features/try-reserve.html"><strong aria-hidden="true">3.130.</strong> try_reserve</a></li><li><a href="library-features/try-trait.html"><strong aria-hidden="true">3.131.</strong> try_trait</a></li><li><a href="library-features/unicode.html"><strong aria-hidden="true">3.132.</strong> unicode</a></li><li><a href="library-features/unicode-internals.html"><strong aria-hidden="true">3.133.</strong> unicode_internals</a></li><li><a href="library-features/unicode-version.html"><strong aria-hidden="true">3.134.</strong> unicode_version</a></li><li><a href="library-features/unsize.html"><strong aria-hidden="true">3.135.</strong> unsize</a></li><li><a href="library-features/update-panic-count.html"><strong aria-hidden="true">3.136.</strong> update_panic_count</a></li><li><a href="library-features/vec-remove-item.html"><strong aria-hidden="true">3.137.</strong> vec_remove_item</a></li><li><a href="library-features/vec-resize-default.html"><strong aria-hidden="true">3.138.</strong> vec_resize_default</a></li><li><a href="library-features/vec-resize-with.html"><strong aria-hidden="true">3.139.</strong> vec_resize_with</a></li><li><a href="library-features/wait-timeout-until.html"><strong aria-hidden="true">3.140.</strong> wait_timeout_until</a></li><li><a href="library-features/wait-until.html"><strong aria-hidden="true">3.141.</strong> wait_until</a></li><li><a href="library-features/windows-c.html"><strong aria-hidden="true">3.142.</strong> windows_c</a></li><li><a href="library-features/windows-file-type-ext.html"><strong aria-hidden="true">3.143.</strong> windows_file_type_ext</a></li><li><a href="library-features/windows-handle.html"><strong aria-hidden="true">3.144.</strong> windows_handle</a></li><li><a href="library-features/windows-net.html"><strong aria-hidden="true">3.145.</strong> windows_net</a></li><li><a href="library-features/windows-stdio.html"><strong aria-hidden="true">3.146.</strong> windows_stdio</a></li><li><a href="library-features/wrapping-int-impl.html"><strong aria-hidden="true">3.147.</strong> wrapping_int_impl</a></li><li><a href="library-features/wrapping-next-power-of-two.html"><strong aria-hidden="true">3.148.</strong> wrapping_next_power_of_two</a></li></ol></li></ol>
</nav>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<div id="menu-bar" class="menu-bar">
<div id="menu-bar-sticky-container">
<div class="left-buttons">
<button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</button>
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
<i class="fa fa-paint-brush"></i>
</button>
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
<li role="none"><button role="menuitem" class="theme" id="light">Light <span class="default">(default)</span></button></li>
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
</ul>
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
<i class="fa fa-search"></i>
</button>
</div>
<h1 class="menu-title"></h1>
<div class="right-buttons">
<a href="print.html" title="Print this book" aria-label="Print this book">
<i id="print-button" class="fa fa-print"></i>
</a>
</div>
</div>
</div>
<div id="search-wrapper" class="hidden">
<form id="searchbar-outer" class="searchbar-outer">
<input type="search" name="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
</form>
<div id="searchresults-outer" class="searchresults-outer hidden">
<div id="searchresults-header" class="searchresults-header"></div>
<ul id="searchresults">
</ul>
</div>
</div>
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
<script type="text/javascript">
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
</script>
<div id="content" class="content">
<main>
<a class="header" href="print.html#the-unstable-book" id="the-unstable-book"><h1>The Unstable Book</h1></a>
<p>Welcome to the Unstable Book! This book consists of a number of chapters,
each one organized by a "feature flag." That is, when using an unstable
feature of Rust, you must use a flag, like this:</p>
<pre><pre class="playpen"><code class="language-rust">#![feature(box_syntax)]
fn main() {
let five = box 5;
}
</code></pre></pre>
<p>The <code>box_syntax</code> feature <a href="language-features/box-syntax.html">has a chapter</a> describing how to use it.</p>
<p>Because this documentation relates to unstable features, we make no guarantees
that what is contained here is accurate or up to date. It's developed on a
best-effort basis. Each page will have a link to its tracking issue with the
latest developments; you might want to check those as well.</p>
<a class="header" href="print.html#compiler-flags" id="compiler-flags"><h1>Compiler flags</h1></a>
<a class="header" href="print.html#linker-flavor" id="linker-flavor"><h1><code>linker-flavor</code></h1></a>
<p>The tracking issue for this feature is: None</p>
<hr />
<p>Every <code>rustc</code> target defaults to some linker. For example, Linux targets default
to gcc. In some cases, you may want to override the default; you can do that
with the unstable CLI argument: <code>-Z linker-flavor</code>.</p>
<p>Here how you would use this flag to link a Rust binary for the
<code>thumbv7m-none-eabi</code> using LLD instead of GCC.</p>
<pre><code class="language-text">$ xargo rustc --target thumbv7m-none-eabi -- \
-C linker=ld.lld \
-Z linker-flavor=ld \
-Z print-link-args | tr ' ' '\n'
"ld.lld"
"-L"
"$SYSROOT/lib/rustlib/thumbv7m-none-eabi/lib"
"$PWD/target/thumbv7m-none-eabi/debug/deps/app-512e9dbf385f233c.0.o"
"-o"
"$PWD/target/thumbv7m-none-eabi/debug/deps/app-512e9dbf385f233c"
"--gc-sections"
"-L"
"$PWD/target/thumbv7m-none-eabi/debug/deps"
"-L"
"$PWD/target/debug/deps"
"-L"
"$SYSROOT/lib/rustlib/thumbv7m-none-eabi/lib"
"-Bstatic"
"$SYSROOT/lib/rustlib/thumbv7m-none-eabi/lib/libcore-e1ccb7dfb1cb9ebb.rlib"
"-Bdynamic"
</code></pre>
<p>Whereas the default is:</p>
<pre><code class="language-text">$ xargo rustc --target thumbv7m-none-eabi -- \
-C link-arg=-nostartfiles \
-Z print-link-args | tr ' ' '\n'
"arm-none-eabi-gcc"
"-L"
"$SYSROOT/lib/rustlib/thumbv7m-none-eabi/lib"
"$PWD/target/thumbv7m-none-eabi/debug/deps/app-961e39416baa38d9.0.o"
"-o"
"$PWD/target/thumbv7m-none-eabi/debug/deps/app-961e39416baa38d9"
"-Wl,--gc-sections"
"-nodefaultlibs"
"-L"
"$PWD/target/thumbv7m-none-eabi/debug/deps"
"-L"
"$PWD/target/debug/deps"
"-L"
"$SYSROOT/lib/rustlib/thumbv7m-none-eabi/lib"
"-Wl,-Bstatic"
"$SYSROOT/lib/rustlib/thumbv7m-none-eabi/lib/libcore-e1ccb7dfb1cb9ebb.rlib"
"-nostartfiles"
"-Wl,-Bdynamic"
</code></pre>
<a class="header" href="print.html#profile" id="profile"><h1><code>profile</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/42524">#42524</a>.</p>
<hr />
<p>This feature allows the generation of code coverage reports.</p>
<p>Set the <code>-Zprofile</code> compiler flag in order to enable gcov profiling.</p>
<p>For example:</p>
<pre><code class="language-Bash">cargo new testgcov --bin
cd testgcov
export RUSTFLAGS="-Zprofile"
cargo build
cargo run
</code></pre>
<p>Once you've built and run your program, files with the <code>gcno</code> (after build) and <code>gcda</code> (after execution) extensions will be created.
You can parse them with <a href="http://llvm.org/docs/CommandGuide/llvm-cov.html#llvm-cov-gcov">llvm-cov gcov</a> or <a href="https://github.com/marco-c/grcov">grcov</a>.</p>
<a class="header" href="print.html#language-features" id="language-features"><h1>Language features</h1></a>
<a class="header" href="print.html#aarch64_target_feature" id="aarch64_target_feature"><h1><code>aarch64_target_feature</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/44839">#44839</a></p>
<hr />
<a class="header" href="print.html#abi_msp430_interrupt" id="abi_msp430_interrupt"><h1><code>abi_msp430_interrupt</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/38487">#38487</a></p>
<hr />
<p>In the MSP430 architecture, interrupt handlers have a special calling
convention. You can use the <code>"msp430-interrupt"</code> ABI to make the compiler apply
the right calling convention to the interrupt handlers you define.</p>
<!-- NOTE(ignore) this example is specific to the msp430 target -->
<pre><code class="language-rust ignore">#![feature(abi_msp430_interrupt)]
#![no_std]
// Place the interrupt handler at the appropriate memory address
// (Alternatively, you can use `#[used]` and remove `pub` and `#[no_mangle]`)
#[link_section = "__interrupt_vector_10"]
#[no_mangle]
pub static TIM0_VECTOR: extern "msp430-interrupt" fn() = tim0;
// The interrupt handler
extern "msp430-interrupt" fn tim0() {
// ..
}
</code></pre>
<pre><code class="language-text">$ msp430-elf-objdump -CD ./target/msp430/release/app
Disassembly of section __interrupt_vector_10:
0000fff2 <TIM0_VECTOR>:
fff2: 00 c0 interrupt service routine at 0xc000
Disassembly of section .text:
0000c000 <int::tim0>:
c000: 00 13 reti
</code></pre>
<a class="header" href="print.html#abi_ptx" id="abi_ptx"><h1><code>abi_ptx</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/38788">#38788</a></p>
<hr />
<p>When emitting PTX code, all vanilla Rust functions (<code>fn</code>) get translated to
"device" functions. These functions are <em>not</em> callable from the host via the
CUDA API so a crate with only device functions is not too useful!</p>
<p>OTOH, "global" functions <em>can</em> be called by the host; you can think of them
as the real public API of your crate. To produce a global function use the
<code>"ptx-kernel"</code> ABI.</p>
<!-- NOTE(ignore) this example is specific to the nvptx targets -->
<pre><code class="language-rust ignore">#![feature(abi_ptx)]
#![no_std]
pub unsafe extern "ptx-kernel" fn global_function() {
device_function();
}
pub fn device_function() {
// ..
}
</code></pre>
<pre><code class="language-text">$ xargo rustc --target nvptx64-nvidia-cuda --release -- --emit=asm
$ cat $(find -name '*.s')
//
// Generated by LLVM NVPTX Back-End
//
.version 3.2
.target sm_20
.address_size 64
// .globl _ZN6kernel15global_function17h46111ebe6516b382E
.visible .entry _ZN6kernel15global_function17h46111ebe6516b382E()
{
ret;
}
// .globl _ZN6kernel15device_function17hd6a0e4993bbf3f78E
.visible .func _ZN6kernel15device_function17hd6a0e4993bbf3f78E()
{
ret;
}
</code></pre>
<a class="header" href="print.html#abi_thiscall" id="abi_thiscall"><h1><code>abi_thiscall</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/42202">#42202</a></p>
<hr />
<p>The MSVC ABI on x86 Windows uses the <code>thiscall</code> calling convention for C++
instance methods by default; it is identical to the usual (C) calling
convention on x86 Windows except that the first parameter of the method,
the <code>this</code> pointer, is passed in the ECX register.</p>
<a class="header" href="print.html#abi_unadjusted" id="abi_unadjusted"><h1><code>abi_unadjusted</code></h1></a>
<p>This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.</p>
<hr />
<a class="header" href="print.html#abi_vectorcall" id="abi_vectorcall"><h1><code>abi_vectorcall</code></h1></a>
<p>This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.</p>
<hr />
<a class="header" href="print.html#abi_x86_interrupt" id="abi_x86_interrupt"><h1><code>abi_x86_interrupt</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/40180">#40180</a></p>
<hr />
<a class="header" href="print.html#allocator_internals" id="allocator_internals"><h1><code>allocator_internals</code></h1></a>
<p>This feature does not have a tracking issue, it is an unstable implementation
detail of the <code>global_allocator</code> feature not intended for use outside the
compiler.</p>
<hr />
<a class="header" href="print.html#allow_fail" id="allow_fail"><h1><code>allow_fail</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/42219">#42219</a></p>
<hr />
<a class="header" href="print.html#allow_internal_unsafe" id="allow_internal_unsafe"><h1><code>allow_internal_unsafe</code></h1></a>
<p>This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.</p>
<hr />
<a class="header" href="print.html#allow_internal_unstable" id="allow_internal_unstable"><h1><code>allow_internal_unstable</code></h1></a>
<p>This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.</p>
<hr />
<a class="header" href="print.html#arbitrary_self_types" id="arbitrary_self_types"><h1><code>arbitrary_self_types</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/44874">#44874</a></p>
<hr />
<a class="header" href="print.html#arm_target_feature" id="arm_target_feature"><h1><code>arm_target_feature</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/44839">#44839</a></p>
<hr />
<a class="header" href="print.html#asm" id="asm"><h1><code>asm</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/29722">#29722</a></p>
<hr />
<p>For extremely low-level manipulations and performance reasons, one
might wish to control the CPU directly. Rust supports using inline
assembly to do this via the <code>asm!</code> macro.</p>
<pre><code class="language-rust ignore">asm!(assembly template
: output operands
: input operands
: clobbers
: options
);
</code></pre>
<p>Any use of <code>asm</code> is feature gated (requires <code>#![feature(asm)]</code> on the
crate to allow) and of course requires an <code>unsafe</code> block.</p>
<blockquote>
<p><strong>Note</strong>: the examples here are given in x86/x86-64 assembly, but
all platforms are supported.</p>
</blockquote>
<a class="header" href="print.html#assembly-template" id="assembly-template"><h2>Assembly template</h2></a>
<p>The <code>assembly template</code> is the only required parameter and must be a
literal string (i.e. <code>""</code>)</p>
<pre><pre class="playpen"><code class="language-rust">#![feature(asm)]
#[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
fn foo() {
unsafe {
asm!("NOP");
}
}
// Other platforms:
#[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))]
fn foo() { /* ... */ }
fn main() {
// ...
foo();
// ...
}
</code></pre></pre>
<p>(The <code>feature(asm)</code> and <code>#[cfg]</code>s are omitted from now on.)</p>
<p>Output operands, input operands, clobbers and options are all optional
but you must add the right number of <code>:</code> if you skip them:</p>
<pre><pre class="playpen"><code class="language-rust"># #![feature(asm)]
# #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
# fn main() { unsafe {
asm!("xor %eax, %eax"
:
:
: "eax"
);
# } }
# #[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))]
# fn main() {}
</code></pre></pre>
<p>Whitespace also doesn't matter:</p>
<pre><pre class="playpen"><code class="language-rust"># #![feature(asm)]
# #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
# fn main() { unsafe {
asm!("xor %eax, %eax" ::: "eax");
# } }
# #[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))]
# fn main() {}
</code></pre></pre>
<a class="header" href="print.html#operands" id="operands"><h2>Operands</h2></a>
<p>Input and output operands follow the same format: <code>: "constraints1"(expr1), "constraints2"(expr2), ..."</code>. Output operand
expressions must be mutable lvalues, or not yet assigned:</p>
<pre><pre class="playpen"><code class="language-rust"># #![feature(asm)]
# #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
fn add(a: i32, b: i32) -> i32 {
let c: i32;
unsafe {
asm!("add $2, $0"
: "=r"(c)
: "0"(a), "r"(b)
);
}
c
}
# #[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))]
# fn add(a: i32, b: i32) -> i32 { a + b }
fn main() {
assert_eq!(add(3, 14159), 14162)
}
</code></pre></pre>
<p>If you would like to use real operands in this position, however,
you are required to put curly braces <code>{}</code> around the register that
you want, and you are required to put the specific size of the
operand. This is useful for very low level programming, where
which register you use is important:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
# #![feature(asm)]
# #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
# unsafe fn read_byte_in(port: u16) -> u8 {
let result: u8;
asm!("in %dx, %al" : "={al}"(result) : "{dx}"(port));
result
# }
#}</code></pre></pre>
<a class="header" href="print.html#clobbers" id="clobbers"><h2>Clobbers</h2></a>
<p>Some instructions modify registers which might otherwise have held
different values so we use the clobbers list to indicate to the
compiler not to assume any values loaded into those registers will
stay valid.</p>
<pre><pre class="playpen"><code class="language-rust"># #![feature(asm)]
# #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
# fn main() { unsafe {
// Put the value 0x200 in eax:
asm!("mov $$0x200, %eax" : /* no outputs */ : /* no inputs */ : "eax");
# } }
# #[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))]
# fn main() {}
</code></pre></pre>
<p>Input and output registers need not be listed since that information
is already communicated by the given constraints. Otherwise, any other
registers used either implicitly or explicitly should be listed.</p>
<p>If the assembly changes the condition code register <code>cc</code> should be
specified as one of the clobbers. Similarly, if the assembly modifies
memory, <code>memory</code> should also be specified.</p>
<a class="header" href="print.html#options" id="options"><h2>Options</h2></a>
<p>The last section, <code>options</code> is specific to Rust. The format is comma
separated literal strings (i.e. <code>:"foo", "bar", "baz"</code>). It's used to
specify some extra info about the inline assembly:</p>
<p>Current valid options are:</p>
<ol>
<li><em>volatile</em> - specifying this is analogous to
<code>__asm__ __volatile__ (...)</code> in gcc/clang.</li>
<li><em>alignstack</em> - certain instructions expect the stack to be
aligned a certain way (i.e. SSE) and specifying this indicates to
the compiler to insert its usual stack alignment code</li>
<li><em>intel</em> - use intel syntax instead of the default AT&T.</li>
</ol>
<pre><pre class="playpen"><code class="language-rust"># #![feature(asm)]
# #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
# fn main() {
let result: i32;
unsafe {
asm!("mov eax, 2" : "={eax}"(result) : : : "intel")
}
println!("eax is currently {}", result);
# }
# #[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))]
# fn main() {}
</code></pre></pre>
<a class="header" href="print.html#more-information" id="more-information"><h2>More Information</h2></a>
<p>The current implementation of the <code>asm!</code> macro is a direct binding to <a href="http://llvm.org/docs/LangRef.html#inline-assembler-expressions">LLVM's
inline assembler expressions</a>, so be sure to check out <a href="http://llvm.org/docs/LangRef.html#inline-assembler-expressions">their
documentation as well</a> for more information about clobbers,
constraints, etc.</p>
<p>If you need more power and don't mind losing some of the niceties of
<code>asm!</code>, check out <a href="language-features/global-asm.html">global_asm</a>.</p>
<a class="header" href="print.html#associated_type_defaults" id="associated_type_defaults"><h1><code>associated_type_defaults</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/29661">#29661</a></p>
<hr />
<a class="header" href="print.html#attr_literals" id="attr_literals"><h1><code>attr_literals</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/34981">#34981</a></p>
<hr />
<p>At present, literals are only accepted as the value of a key-value pair in
attributes. What's more, only <em>string</em> literals are accepted. This means that
literals can only appear in forms of <code>#[attr(name = "value")]</code> or
<code>#[attr = "value"]</code>.</p>
<p>The <code>attr_literals</code> unstable feature allows other types of literals to be used
in attributes. Here are some examples of attributes that can now be used with
this feature enabled:</p>
<pre><code class="language-rust ignore">#[attr]
#[attr(true)]
#[attr(ident)]
#[attr(ident, 100, true, "true", ident = 100, ident = "hello", ident(100))]
#[attr(100)]
#[attr(enabled = true)]
#[enabled(true)]
#[attr("hello")]
#[repr(C, align = 4)]
#[repr(C, align(4))]
</code></pre>
<a class="header" href="print.html#avx512_target_feature" id="avx512_target_feature"><h1><code>avx512_target_feature</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/44839">#44839</a></p>
<hr />
<a class="header" href="print.html#box_patterns" id="box_patterns"><h1><code>box_patterns</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/29641">#29641</a></p>
<p>See also <a href="language-features/box-syntax.html"><code>box_syntax</code></a></p>
<hr />
<p>Box patterns let you match on <code>Box<T></code>s:</p>
<pre><pre class="playpen"><code class="language-rust">#![feature(box_patterns)]
fn main() {
let b = Some(Box::new(5));
match b {
Some(box n) if n < 0 => {
println!("Box contains negative number {}", n);
},
Some(box n) if n >= 0 => {
println!("Box contains non-negative number {}", n);
},
None => {
println!("No box");
},
_ => unreachable!()
}
}
</code></pre></pre>
<a class="header" href="print.html#box_syntax" id="box_syntax"><h1><code>box_syntax</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/49733">#49733</a></p>
<p>See also <a href="language-features/box-patterns.html"><code>box_patterns</code></a></p>
<hr />
<p>Currently the only stable way to create a <code>Box</code> is via the <code>Box::new</code> method.
Also it is not possible in stable Rust to destructure a <code>Box</code> in a match
pattern. The unstable <code>box</code> keyword can be used to create a <code>Box</code>. An example
usage would be:</p>
<pre><pre class="playpen"><code class="language-rust">#![feature(box_syntax)]
fn main() {
let b = box 5;
}
</code></pre></pre>
<a class="header" href="print.html#catch_expr" id="catch_expr"><h1><code>catch_expr</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/31436">#31436</a></p>
<hr />
<p>The <code>catch_expr</code> feature adds support for a <code>catch</code> expression. The <code>catch</code>
expression creates a new scope one can use the <code>?</code> operator in.</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#![feature(catch_expr)]
#fn main() {
use std::num::ParseIntError;
let result: Result<i32, ParseIntError> = do catch {
"1".parse::<i32>()?
+ "2".parse::<i32>()?
+ "3".parse::<i32>()?
};
assert_eq!(result, Ok(6));
let result: Result<i32, ParseIntError> = do catch {
"1".parse::<i32>()?
+ "foo".parse::<i32>()?
+ "3".parse::<i32>()?
};
assert!(result.is_err());
#}</code></pre></pre>
<a class="header" href="print.html#cfg_target_has_atomic" id="cfg_target_has_atomic"><h1><code>cfg_target_has_atomic</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/32976">#32976</a></p>
<hr />
<a class="header" href="print.html#cfg_target_thread_local" id="cfg_target_thread_local"><h1><code>cfg_target_thread_local</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/29594">#29594</a></p>
<hr />
<a class="header" href="print.html#cfg_target_vendor" id="cfg_target_vendor"><h1><code>cfg_target_vendor</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/29718">#29718</a></p>
<hr />
<a class="header" href="print.html#compiler_builtins" id="compiler_builtins"><h1><code>compiler_builtins</code></h1></a>
<p>This feature is internal to the Rust compiler and is not intended for general use.</p>
<hr />
<a class="header" href="print.html#concat_idents" id="concat_idents"><h1><code>concat_idents</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/29599">#29599</a></p>
<hr />
<p>The <code>concat_idents</code> feature adds a macro for concatenating multiple identifiers
into one identifier.</p>
<a class="header" href="print.html#examples" id="examples"><h2>Examples</h2></a>
<pre><pre class="playpen"><code class="language-rust">#![feature(concat_idents)]
fn main() {
fn foobar() -> u32 { 23 }
let f = concat_idents!(foo, bar);
assert_eq!(f(), 23);
}
</code></pre></pre>
<a class="header" href="print.html#const_fn" id="const_fn"><h1><code>const_fn</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/24111">#24111</a></p>
<hr />
<p>The <code>const_fn</code> feature allows marking free functions and inherent methods as
<code>const</code>, enabling them to be called in constants contexts, with constant
arguments.</p>
<a class="header" href="print.html#examples-1" id="examples-1"><h2>Examples</h2></a>
<pre><pre class="playpen"><code class="language-rust">#![feature(const_fn)]
const fn double(x: i32) -> i32 {
x * 2
}
const FIVE: i32 = 5;
const TEN: i32 = double(FIVE);
fn main() {
assert_eq!(5, FIVE);
assert_eq!(10, TEN);
}
</code></pre></pre>
<a class="header" href="print.html#const_let" id="const_let"><h1><code>const_let</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/48821">#48821</a></p>
<hr />
<a class="header" href="print.html#crate_in_paths" id="crate_in_paths"><h1><code>crate_in_paths</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/44660">#44660</a></p>
<hr />
<p>The <code>crate_in_paths</code> feature allows to explicitly refer to the crate root in absolute paths
using keyword <code>crate</code>.</p>
<p><code>crate</code> can be used <em>only</em> in absolute paths, i.e. either in <code>::crate::a::b::c</code> form or in <code>use</code>
items where the starting <code>::</code> is added implicitly.<br />
Paths like <code>crate::a::b::c</code> are not accepted currently.</p>
<p>This feature is required in <code>feature(extern_absolute_paths)</code> mode to refer to any absolute path
in the local crate (absolute paths refer to extern crates by default in that mode), but can be
used without <code>feature(extern_absolute_paths)</code> as well.</p>
<pre><pre class="playpen"><code class="language-rust">#![feature(crate_in_paths)]
// Imports, `::` is added implicitly
use crate::m::f;
use crate as root;
mod m {
pub fn f() -> u8 { 1 }
pub fn g() -> u8 { 2 }
pub fn h() -> u8 { 3 }
// OK, visibilities implicitly add starting `::` as well, like imports
pub(in crate::m) struct S;
}
mod n
{
use crate::m::f;
use crate as root;
pub fn check() {
assert_eq!(f(), 1);
// `::` is required in non-import paths
assert_eq!(::crate::m::g(), 2);
assert_eq!(root::m::h(), 3);
}
}
fn main() {
assert_eq!(f(), 1);
assert_eq!(::crate::m::g(), 2);
assert_eq!(root::m::h(), 3);
n::check();
}
</code></pre></pre>
<a class="header" href="print.html#crate_visibility_modifier" id="crate_visibility_modifier"><h1><code>crate_visibility_modifier</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/45388">#45388</a></p>
<hr />
<p>The <code>crate_visibility_modifier</code> feature allows the <code>crate</code> keyword to be used
as a visibility modifier synonymous to <code>pub(crate)</code>, indicating that a type
(function, <em>&c.</em>) is to be visible to the entire enclosing crate, but not to
other crates.</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#![feature(crate_visibility_modifier)]
#fn main() {
crate struct Foo {
bar: usize,
}
#}</code></pre></pre>
<a class="header" href="print.html#custom_attribute" id="custom_attribute"><h1><code>custom_attribute</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/29642">#29642</a></p>
<hr />
<a class="header" href="print.html#custom_derive" id="custom_derive"><h1><code>custom_derive</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/29644">#29644</a></p>
<hr />
<a class="header" href="print.html#decl_macro" id="decl_macro"><h1><code>decl_macro</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/39412">#39412</a></p>
<hr />
<a class="header" href="print.html#default_type_parameter_fallback" id="default_type_parameter_fallback"><h1><code>default_type_parameter_fallback</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/27336">#27336</a></p>
<hr />
<a class="header" href="print.html#doc_alias" id="doc_alias"><h1><code>doc_alias</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/50146">#50146</a></p>
<hr />
<p>You can add alias(es) to an item when using the <code>rustdoc</code> search through the
<code>doc(alias)</code> attribute. Example:</p>
<pre><pre class="playpen"><code class="language-rust no_run">
# #![allow(unused_variables)]
#![feature(doc_alias)]
#fn main() {
#[doc(alias = "x")]
#[doc(alias = "big")]
pub struct BigX;
#}</code></pre></pre>
<p>Then, when looking for it through the <code>rustdoc</code> search, if you enter "x" or
"big", search will show the <code>BigX</code> struct first.</p>
<p>Note that this feature is currently hidden behind the <code>feature(doc_alias)</code> gate.</p>
<a class="header" href="print.html#doc_cfg" id="doc_cfg"><h1><code>doc_cfg</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/43781">#43781</a></p>
<hr />
<p>The <code>doc_cfg</code> feature allows an API be documented as only available in some specific platforms.
This attribute has two effects:</p>
<ol>
<li>
<p>In the annotated item's documentation, there will be a message saying "This is supported on
(platform) only".</p>
</li>
<li>
<p>The item's doc-tests will only run on the specific platform.</p>
</li>
</ol>
<p>This feature was introduced as part of PR <a href="https://github.com/rust-lang/rust/issues/43348">#43348</a> to allow the platform-specific parts of the
standard library be documented.</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#![feature(doc_cfg)]
#fn main() {
#[cfg(any(windows, feature = "documentation"))]
#[doc(cfg(windows))]
/// The application's icon in the notification area (a.k.a. system tray).
///
/// # Examples
///
/// ```no_run
/// extern crate my_awesome_ui_library;
/// use my_awesome_ui_library::current_app;
/// use my_awesome_ui_library::windows::notification;
///
/// let icon = current_app().get::<notification::Icon>();
/// icon.show();
/// icon.show_message("Hello");
/// ```
pub struct Icon {
// ...
}
#}</code></pre></pre>
<a class="header" href="print.html#doc_keyword" id="doc_keyword"><h1><code>doc_keyword</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/51315">#51315</a></p>
<hr />
<a class="header" href="print.html#doc_masked" id="doc_masked"><h1><code>doc_masked</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/pull/44027">#44027</a></p>
<hr />
<p>The <code>doc_masked</code> feature allows a crate to exclude types from a given crate from appearing in lists
of trait implementations. The specifics of the feature are as follows:</p>
<ol>
<li>
<p>When rustdoc encounters an <code>extern crate</code> statement annotated with a <code>#[doc(masked)]</code> attribute,
it marks the crate as being masked.</p>
</li>
<li>
<p>When listing traits a given type implements, rustdoc ensures that traits from masked crates are
not emitted into the documentation.</p>
</li>
<li>
<p>When listing types that implement a given trait, rustdoc ensures that types from masked crates
are not emitted into the documentation.</p>
</li>
</ol>
<p>This feature was introduced in PR <a href="https://github.com/rust-lang/rust/pull/44026">#44026</a> to ensure that compiler-internal and
implementation-specific types and traits were not included in the standard library's documentation.
Such types would introduce broken links into the documentation.</p>
<a class="header" href="print.html#doc_spotlight" id="doc_spotlight"><h1><code>doc_spotlight</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/45040">#45040</a></p>
<p>The <code>doc_spotlight</code> feature allows the use of the <code>spotlight</code> parameter to the <code>#[doc]</code> attribute,
to "spotlight" a specific trait on the return values of functions. Adding a <code>#[doc(spotlight)]</code>
attribute to a trait definition will make rustdoc print extra information for functions which return
a type that implements that trait. This attribute is applied to the <code>Iterator</code>, <code>io::Read</code>, and
<code>io::Write</code> traits in the standard library.</p>
<p>You can do this on your own traits, like this:</p>
<pre><code>#![feature(doc_spotlight)]
#[doc(spotlight)]
pub trait MyTrait {}
pub struct MyStruct;
impl MyTrait for MyStruct {}
/// The docs for this function will have an extra line about `MyStruct` implementing `MyTrait`,
/// without having to write that yourself!
pub fn my_fn() -> MyStruct { MyStruct }
</code></pre>
<p>This feature was originally implemented in PR <a href="https://github.com/rust-lang/rust/pull/45039">#45039</a>.</p>
<a class="header" href="print.html#dropck_eyepatch" id="dropck_eyepatch"><h1><code>dropck_eyepatch</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/34761">#34761</a></p>
<hr />
<a class="header" href="print.html#dropck_parametricity" id="dropck_parametricity"><h1><code>dropck_parametricity</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/28498">#28498</a></p>
<hr />
<a class="header" href="print.html#exclusive_range_pattern" id="exclusive_range_pattern"><h1><code>exclusive_range_pattern</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/37854">#37854</a></p>
<hr />
<a class="header" href="print.html#exhaustive_patterns" id="exhaustive_patterns"><h1><code>exhaustive_patterns</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/51085">#51085</a></p>
<hr />
<a class="header" href="print.html#extern_absolute_paths" id="extern_absolute_paths"><h1><code>extern_absolute_paths</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/44660">#44660</a></p>
<hr />
<p>The <code>extern_absolute_paths</code> feature enables mode allowing to refer to names from other crates
"inline", without introducing <code>extern crate</code> items, using absolute paths like <code>::my_crate::a::b</code>.</p>
<p><code>::my_crate::a::b</code> will resolve to path <code>a::b</code> in crate <code>my_crate</code>.</p>
<p><code>feature(crate_in_paths)</code> can be used in <code>feature(extern_absolute_paths)</code> mode for referring
to absolute paths in the local crate (<code>::crate::a::b</code>).</p>
<p><code>feature(extern_in_paths)</code> provides the same effect by using keyword <code>extern</code> to refer to
paths from other crates (<code>extern::my_crate::a::b</code>).</p>
<pre><code class="language-rust ignore">#![feature(extern_absolute_paths)]
// Suppose we have a dependency crate `xcrate` available through `Cargo.toml`, or `--extern`
// options, or standard Rust distribution, or some other means.
use xcrate::Z;
fn f() {
use xcrate;
use xcrate as ycrate;
let s = xcrate::S;
assert_eq!(format!("{:?}", s), "S");
let z = ycrate::Z;
assert_eq!(format!("{:?}", z), "Z");
}
fn main() {
let s = ::xcrate::S;
assert_eq!(format!("{:?}", s), "S");
let z = Z;
assert_eq!(format!("{:?}", z), "Z");
}
</code></pre>
<a class="header" href="print.html#extern_in_paths" id="extern_in_paths"><h1><code>extern_in_paths</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/44660">#44660</a></p>
<hr />
<p>The <code>extern_in_paths</code> feature allows to refer to names from other crates "inline", without
introducing <code>extern crate</code> items, using keyword <code>extern</code>.</p>
<p>For example, <code>extern::my_crat::a::b</code> will resolve to path <code>a::b</code> in crate <code>my_crate</code>.</p>
<p><code>feature(extern_absolute_paths)</code> mode provides the same effect by resolving absolute paths like
<code>::my_crate::a::b</code> to paths from extern crates by default.</p>
<pre><code class="language-rust ignore">#![feature(extern_in_paths)]
// Suppose we have a dependency crate `xcrate` available through `Cargo.toml`, or `--extern`
// options, or standard Rust distribution, or some other means.
use extern::xcrate::Z;
fn f() {
use extern::xcrate;
use extern::xcrate as ycrate;
let s = xcrate::S;
assert_eq!(format!("{:?}", s), "S");
let z = ycrate::Z;
assert_eq!(format!("{:?}", z), "Z");
}
fn main() {
let s = extern::xcrate::S;
assert_eq!(format!("{:?}", s), "S");
let z = Z;
assert_eq!(format!("{:?}", z), "Z");
}
</code></pre>
<a class="header" href="print.html#extern_prelude" id="extern_prelude"><h1><code>extern_prelude</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/44660">#44660</a></p>
<hr />
<a class="header" href="print.html#extern_types" id="extern_types"><h1><code>extern_types</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/43467">#43467</a></p>
<hr />
<a class="header" href="print.html#external_doc" id="external_doc"><h1><code>external_doc</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/44732">#44732</a></p>
<p>The <code>external_doc</code> feature allows the use of the <code>include</code> parameter to the <code>#[doc]</code> attribute, to
include external files in documentation. Use the attribute in place of, or in addition to, regular
doc comments and <code>#[doc]</code> attributes, and <code>rustdoc</code> will load the given file when it renders
documentation for your crate.</p>
<p>With the following files in the same directory:</p>
<p><code>external-doc.md</code>:</p>
<pre><code class="language-markdown"># My Awesome Type
This is the documentation for this spectacular type.
</code></pre>
<p><code>lib.rs</code>:</p>
<pre><code class="language-no_run(needs-external-files)">#![feature(external_doc)]
#[doc(include = "external-doc.md")]
pub struct MyAwesomeType;
</code></pre>
<p><code>rustdoc</code> will load the file <code>external-doc.md</code> and use it as the documentation for the <code>MyAwesomeType</code>
struct.</p>
<p>When locating files, <code>rustdoc</code> will base paths in the <code>src/</code> directory, as if they were alongside the
<code>lib.rs</code> for your crate. So if you want a <code>docs/</code> folder to live alongside the <code>src/</code> directory,
start your paths with <code>../docs/</code> for <code>rustdoc</code> to properly find the file.</p>
<p>This feature was proposed in <a href="https://github.com/rust-lang/rfcs/pull/1990">RFC #1990</a> and initially implemented in PR <a href="https://github.com/rust-lang/rust/pull/44781">#44781</a>.</p>
<a class="header" href="print.html#fundamental" id="fundamental"><h1><code>fundamental</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/29635">#29635</a></p>
<hr />
<a class="header" href="print.html#generators" id="generators"><h1><code>generators</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/43122">#43122</a></p>
<hr />
<p>The <code>generators</code> feature gate in Rust allows you to define generator or
coroutine literals. A generator is a "resumable function" that syntactically
resembles a closure but compiles to much different semantics in the compiler
itself. The primary feature of a generator is that it can be suspended during
execution to be resumed at a later date. Generators use the <code>yield</code> keyword to
"return", and then the caller can <code>resume</code> a generator to resume execution just
after the <code>yield</code> keyword.</p>
<p>Generators are an extra-unstable feature in the compiler right now. Added in
<a href="https://github.com/rust-lang/rfcs/pull/2033">RFC 2033</a> they're mostly intended right now as a information/constraint
gathering phase. The intent is that experimentation can happen on the nightly
compiler before actual stabilization. A further RFC will be required to
stabilize generators/coroutines and will likely contain at least a few small
tweaks to the overall design.</p>
<p>A syntactical example of a generator is:</p>
<pre><pre class="playpen"><code class="language-rust">#![feature(generators, generator_trait)]
use std::ops::{Generator, GeneratorState};
fn main() {
let mut generator = || {
yield 1;
return "foo"
};
match unsafe { generator.resume() } {
GeneratorState::Yielded(1) => {}
_ => panic!("unexpected value from resume"),
}
match unsafe { generator.resume() } {
GeneratorState::Complete("foo") => {}
_ => panic!("unexpected value from resume"),
}
}
</code></pre></pre>
<p>Generators are closure-like literals which can contain a <code>yield</code> statement. The
<code>yield</code> statement takes an optional expression of a value to yield out of the
generator. All generator literals implement the <code>Generator</code> trait in the
<code>std::ops</code> module. The <code>Generator</code> trait has one main method, <code>resume</code>, which
resumes execution of the generator at the previous suspension point.</p>
<p>An example of the control flow of generators is that the following example
prints all numbers in order:</p>
<pre><pre class="playpen"><code class="language-rust">#![feature(generators, generator_trait)]
use std::ops::Generator;
fn main() {
let mut generator = || {
println!("2");
yield;
println!("4");
};
println!("1");
unsafe { generator.resume() };
println!("3");
unsafe { generator.resume() };
println!("5");
}
</code></pre></pre>
<p>At this time the main intended use case of generators is an implementation
primitive for async/await syntax, but generators will likely be extended to
ergonomic implementations of iterators and other primitives in the future.
Feedback on the design and usage is always appreciated!</p>
<a class="header" href="print.html#the-generator-trait" id="the-generator-trait"><h3>The <code>Generator</code> trait</h3></a>
<p>The <code>Generator</code> trait in <code>std::ops</code> currently looks like:</p>
<pre><code># #![feature(generator_trait)]
# use std::ops::GeneratorState;
pub trait Generator {
type Yield;
type Return;
unsafe fn resume(&mut self) -> GeneratorState<Self::Yield, Self::Return>;
}
</code></pre>
<p>The <code>Generator::Yield</code> type is the type of values that can be yielded with the
<code>yield</code> statement. The <code>Generator::Return</code> type is the returned type of the
generator. This is typically the last expression in a generator's definition or
any value passed to <code>return</code> in a generator. The <code>resume</code> function is the entry
point for executing the <code>Generator</code> itself.</p>
<p>The return value of <code>resume</code>, <code>GeneratorState</code>, looks like:</p>
<pre><code>pub enum GeneratorState<Y, R> {
Yielded(Y),
Complete(R),
}
</code></pre>
<p>The <code>Yielded</code> variant indicates that the generator can later be resumed. This
corresponds to a <code>yield</code> point in a generator. The <code>Complete</code> variant indicates
that the generator is complete and cannot be resumed again. Calling <code>resume</code>
after a generator has returned <code>Complete</code> will likely result in a panic of the
program.</p>
<a class="header" href="print.html#closure-like-semantics" id="closure-like-semantics"><h3>Closure-like semantics</h3></a>
<p>The closure-like syntax for generators alludes to the fact that they also have
closure-like semantics. Namely:</p>
<ul>
<li>
<p>When created, a generator executes no code. A closure literal does not
actually execute any of the closure's code on construction, and similarly a
generator literal does not execute any code inside the generator when
constructed.</p>
</li>
<li>
<p>Generators can capture outer variables by reference or by move, and this can
be tweaked with the <code>move</code> keyword at the beginning of the closure. Like
closures all generators will have an implicit environment which is inferred by
the compiler. Outer variables can be moved into a generator for use as the
generator progresses.</p>
</li>
<li>
<p>Generator literals produce a value with a unique type which implements the
<code>std::ops::Generator</code> trait. This allows actual execution of the generator
through the <code>Generator::resume</code> method as well as also naming it in return
types and such.</p>
</li>
<li>
<p>Traits like <code>Send</code> and <code>Sync</code> are automatically implemented for a <code>Generator</code>
depending on the captured variables of the environment. Unlike closures,
generators also depend on variables live across suspension points. This means
that although the ambient environment may be <code>Send</code> or <code>Sync</code>, the generator
itself may not be due to internal variables live across <code>yield</code> points being
not-<code>Send</code> or not-<code>Sync</code>. Note that generators, like closures, do
not implement traits like <code>Copy</code> or <code>Clone</code> automatically.</p>
</li>
<li>
<p>Whenever a generator is dropped it will drop all captured environment
variables.</p>
</li>
</ul>
<p>Note that unlike closures generators at this time cannot take any arguments.
That is, generators must always look like <code>|| { ... }</code>. This restriction may be
lifted at a future date, the design is ongoing!</p>
<a class="header" href="print.html#generators-as-state-machines" id="generators-as-state-machines"><h3>Generators as state machines</h3></a>
<p>In the compiler, generators are currently compiled as state machines. Each
<code>yield</code> expression will correspond to a different state that stores all live
variables over that suspension point. Resumption of a generator will dispatch on
the current state and then execute internally until a <code>yield</code> is reached, at
which point all state is saved off in the generator and a value is returned.</p>
<p>Let's take a look at an example to see what's going on here:</p>
<pre><pre class="playpen"><code class="language-rust">#![feature(generators, generator_trait)]
use std::ops::Generator;
fn main() {
let ret = "foo";
let mut generator = move || {
yield 1;
return ret
};
unsafe { generator.resume() };
unsafe { generator.resume() };
}
</code></pre></pre>
<p>This generator literal will compile down to something similar to:</p>
<pre><pre class="playpen"><code class="language-rust">#![feature(generators, generator_trait)]
use std::ops::{Generator, GeneratorState};
fn main() {
let ret = "foo";
let mut generator = {
enum __Generator {
Start(&'static str),
Yield1(&'static str),
Done,
}
impl Generator for __Generator {
type Yield = i32;
type Return = &'static str;
unsafe fn resume(&mut self) -> GeneratorState<i32, &'static str> {
use std::mem;
match mem::replace(self, __Generator::Done) {
__Generator::Start(s) => {
*self = __Generator::Yield1(s);
GeneratorState::Yielded(1)
}
__Generator::Yield1(s) => {
*self = __Generator::Done;
GeneratorState::Complete(s)
}
__Generator::Done => {
panic!("generator resumed after completion")
}
}
}
}
__Generator::Start(ret)
};
unsafe { generator.resume() };
unsafe { generator.resume() };
}
</code></pre></pre>
<p>Notably here we can see that the compiler is generating a fresh type,
<code>__Generator</code> in this case. This type has a number of states (represented here
as an <code>enum</code>) corresponding to each of the conceptual states of the generator.
At the beginning we're closing over our outer variable <code>foo</code> and then that
variable is also live over the <code>yield</code> point, so it's stored in both states.</p>
<p>When the generator starts it'll immediately yield 1, but it saves off its state
just before it does so indicating that it has reached the yield point. Upon
resuming again we'll execute the <code>return ret</code> which returns the <code>Complete</code>
state.</p>
<p>Here we can also note that the <code>Done</code> state, if resumed, panics immediately as
it's invalid to resume a completed generator. It's also worth noting that this
is just a rough desugaring, not a normative specification for what the compiler
does.</p>
<a class="header" href="print.html#generic_associated_types" id="generic_associated_types"><h1><code>generic_associated_types</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/44265">#44265</a></p>
<hr />
<a class="header" href="print.html#global_asm" id="global_asm"><h1><code>global_asm</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/35119">#35119</a></p>
<hr />
<p>The <code>global_asm!</code> macro allows the programmer to write arbitrary
assembly outside the scope of a function body, passing it through
<code>rustc</code> and <code>llvm</code> to the assembler. The macro is a no-frills
interface to LLVM's concept of <a href="http://llvm.org/docs/LangRef.html#module-level-inline-assembly">module-level inline assembly</a>. That is,
all caveats applicable to LLVM's module-level inline assembly apply
to <code>global_asm!</code>.</p>
<p><code>global_asm!</code> fills a role not currently satisfied by either <code>asm!</code>
or <code>#[naked]</code> functions. The programmer has <em>all</em> features of the
assembler at their disposal. The linker will expect to resolve any
symbols defined in the inline assembly, modulo any symbols marked as
external. It also means syntax for directives and assembly follow the
conventions of the assembler in your toolchain.</p>
<p>A simple usage looks like this:</p>
<pre><code class="language-rust ignore"># #![feature(global_asm)]
# you also need relevant target_arch cfgs
global_asm!(include_str!("something_neato.s"));
</code></pre>
<p>And a more complicated usage looks like this:</p>
<pre><code class="language-rust ignore"># #![feature(global_asm)]
# #![cfg(any(target_arch = "x86", target_arch = "x86_64"))]
pub mod sally {
global_asm!(r#"
.global foo
foo:
jmp baz
"#);
#[no_mangle]
pub unsafe extern "C" fn baz() {}
}
// the symbols `foo` and `bar` are global, no matter where
// `global_asm!` was used.
extern "C" {
fn foo();
fn bar();
}
pub mod harry {
global_asm!(r#"
.global bar
bar:
jmp quux
"#);
#[no_mangle]
pub unsafe extern "C" fn quux() {}
}
</code></pre>
<p>You may use <code>global_asm!</code> multiple times, anywhere in your crate, in
whatever way suits you. The effect is as if you concatenated all
usages and placed the larger, single usage in the crate root.</p>
<hr />
<p>If you don't need quite as much power and flexibility as
<code>global_asm!</code> provides, and you don't mind restricting your inline
assembly to <code>fn</code> bodies only, you might try the
<a href="language-features/asm.html">asm</a> feature instead.</p>
<a class="header" href="print.html#hexagon_target_feature" id="hexagon_target_feature"><h1><code>hexagon_target_feature</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/44839">#44839</a></p>
<hr />
<a class="header" href="print.html#if_while_or_patterns" id="if_while_or_patterns"><h1><code>if_while_or_patterns</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/48215">#48215</a></p>
<hr />
<a class="header" href="print.html#in_band_lifetimes" id="in_band_lifetimes"><h1><code>in_band_lifetimes</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/44524">#44524</a></p>
<hr />
<a class="header" href="print.html#infer_outlives_requirements" id="infer_outlives_requirements"><h1><code>infer_outlives_requirements</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/44493">#44493</a></p>
<hr />
<p>The <code>infer_outlives_requirements</code> feature indicates that certain
outlives requirements can be infered by the compiler rather than
stating them explicitly.</p>
<p>For example, currently generic struct definitions that contain
references, require where-clauses of the form T: 'a. By using
this feature the outlives predicates will be infered, although
they may still be written explicitly.</p>
<pre><code class="language-rust ignore(pseudo-Rust)">struct Foo<'a, T>
where T: 'a // <-- currently required
{
bar: &'a T,
}
</code></pre>
<a class="header" href="print.html#examples-2" id="examples-2"><h2>Examples:</h2></a>
<pre><code class="language-rust ignore(pseudo-Rust)">#![feature(infer_outlives_requirements)]
// Implicitly infer T: 'a
struct Foo<'a, T> {
bar: &'a T,
}
</code></pre>
<pre><code class="language-rust ignore(pseudo-Rust)">#![feature(infer_outlives_requirements)]
// Implicitly infer `U: 'b`
struct Foo<'b, U> {
bar: Bar<'b, U>
}
struct Bar<'a, T> where T: 'a {
x: &'a (),
y: T,
}
</code></pre>
<pre><code class="language-rust ignore(pseudo-Rust)">#![feature(infer_outlives_requirements)]
// Implicitly infer `b': 'a`
struct Foo<'a, 'b, T> {
x: &'a &'b T
}
</code></pre>
<pre><code class="language-rust ignore(pseudo-Rust)">#![feature(infer_outlives_requirements)]
// Implicitly infer `<T as std::iter::Iterator>::Item : 'a`
struct Foo<'a, T: Iterator> {
bar: &'a T::Item
</code></pre>
<a class="header" href="print.html#intrinsics" id="intrinsics"><h1><code>intrinsics</code></h1></a>
<p>The tracking issue for this feature is: None.</p>
<p>Intrinsics are never intended to be stable directly, but intrinsics are often
exported in some sort of stable manner. Prefer using the stable interfaces to
the intrinsic directly when you can.</p>
<hr />
<p>These are imported as if they were FFI functions, with the special
<code>rust-intrinsic</code> ABI. For example, if one was in a freestanding
context, but wished to be able to <code>transmute</code> between types, and
perform efficient pointer arithmetic, one would import those functions
via a declaration like</p>
<pre><pre class="playpen"><code class="language-rust">#![feature(intrinsics)]
# fn main() {}
extern "rust-intrinsic" {
fn transmute<T, U>(x: T) -> U;
fn offset<T>(dst: *const T, offset: isize) -> *const T;
}
</code></pre></pre>
<p>As with any other FFI functions, these are always <code>unsafe</code> to call.</p>
<a class="header" href="print.html#label_break_value" id="label_break_value"><h1><code>label_break_value</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/48594">#48594</a></p>
<hr />
<a class="header" href="print.html#lang_items" id="lang_items"><h1><code>lang_items</code></h1></a>
<p>The tracking issue for this feature is: None.</p>
<hr />
<p>The <code>rustc</code> compiler has certain pluggable operations, that is,
functionality that isn't hard-coded into the language, but is
implemented in libraries, with a special marker to tell the compiler
it exists. The marker is the attribute <code>#[lang = "..."]</code> and there are
various different values of <code>...</code>, i.e. various different 'lang
items'.</p>
<p>For example, <code>Box</code> pointers require two lang items, one for allocation
and one for deallocation. A freestanding program that uses the <code>Box</code>
sugar for dynamic allocations via <code>malloc</code> and <code>free</code>:</p>
<pre><code class="language-rust ignore">#![feature(lang_items, box_syntax, start, libc, core_intrinsics)]
#![no_std]
use core::intrinsics;
use core::panic::PanicInfo;
extern crate libc;
#[lang = "owned_box"]
pub struct Box<T>(*mut T);
#[lang = "exchange_malloc"]
unsafe fn allocate(size: usize, _align: usize) -> *mut u8 {
let p = libc::malloc(size as libc::size_t) as *mut u8;
// Check if `malloc` failed:
if p as usize == 0 {
intrinsics::abort();
}
p
}
#[lang = "box_free"]
unsafe fn box_free<T: ?Sized>(ptr: *mut T) {
libc::free(ptr as *mut libc::c_void)
}
#[start]
fn main(_argc: isize, _argv: *const *const u8) -> isize {
let _x = box 1;
0
}
#[lang = "eh_personality"] extern fn rust_eh_personality() {}
#[lang = "panic_impl"] extern fn rust_begin_panic(info: &PanicInfo) -> ! { unsafe { intrinsics::abort() } }
#[lang = "eh_unwind_resume"] extern fn rust_eh_unwind_resume() {}
#[no_mangle] pub extern fn rust_eh_register_frames () {}
#[no_mangle] pub extern fn rust_eh_unregister_frames () {}
</code></pre>
<p>Note the use of <code>abort</code>: the <code>exchange_malloc</code> lang item is assumed to
return a valid pointer, and so needs to do the check internally.</p>
<p>Other features provided by lang items include:</p>
<ul>
<li>overloadable operators via traits: the traits corresponding to the
<code>==</code>, <code><</code>, dereferencing (<code>*</code>) and <code>+</code> (etc.) operators are all
marked with lang items; those specific four are <code>eq</code>, <code>ord</code>,
<code>deref</code>, and <code>add</code> respectively.</li>
<li>stack unwinding and general failure; the <code>eh_personality</code>,
<code>eh_unwind_resume</code>, <code>fail</code> and <code>fail_bounds_checks</code> lang items.</li>
<li>the traits in <code>std::marker</code> used to indicate types of
various kinds; lang items <code>send</code>, <code>sync</code> and <code>copy</code>.</li>
<li>the marker types and variance indicators found in
<code>std::marker</code>; lang items <code>covariant_type</code>,
<code>contravariant_lifetime</code>, etc.</li>
</ul>
<p>Lang items are loaded lazily by the compiler; e.g. if one never uses
<code>Box</code> then there is no need to define functions for <code>exchange_malloc</code>
and <code>box_free</code>. <code>rustc</code> will emit an error when an item is needed
but not found in the current crate or any that it depends on.</p>
<p>Most lang items are defined by <code>libcore</code>, but if you're trying to build
an executable without the standard library, you'll run into the need
for lang items. The rest of this page focuses on this use-case, even though
lang items are a bit broader than that.</p>
<a class="header" href="print.html#using-libc" id="using-libc"><h3>Using libc</h3></a>
<p>In order to build a <code>#[no_std]</code> executable we will need libc as a dependency.
We can specify this using our <code>Cargo.toml</code> file:</p>
<pre><code class="language-toml">[dependencies]
libc = { version = "0.2.14", default-features = false }
</code></pre>
<p>Note that the default features have been disabled. This is a critical step -
<strong>the default features of libc include the standard library and so must be
disabled.</strong></p>
<a class="header" href="print.html#writing-an-executable-without-stdlib" id="writing-an-executable-without-stdlib"><h3>Writing an executable without stdlib</h3></a>
<p>Controlling the entry point is possible in two ways: the <code>#[start]</code> attribute,
or overriding the default shim for the C <code>main</code> function with your own.</p>
<p>The function marked <code>#[start]</code> is passed the command line parameters
in the same format as C:</p>
<pre><code class="language-rust ignore">#![feature(lang_items, core_intrinsics)]
#![feature(start)]
#![no_std]
use core::intrinsics;
use core::panic::PanicInfo;
// Pull in the system libc library for what crt0.o likely requires.
extern crate libc;
// Entry point for this program.
#[start]
fn start(_argc: isize, _argv: *const *const u8) -> isize {
0
}
// These functions are used by the compiler, but not
// for a bare-bones hello world. These are normally
// provided by libstd.
#[lang = "eh_personality"]
#[no_mangle]
pub extern fn rust_eh_personality() {
}
// This function may be needed based on the compilation target.
#[lang = "eh_unwind_resume"]
#[no_mangle]
pub extern fn rust_eh_unwind_resume() {
}
#[lang = "panic_impl"]
#[no_mangle]
pub extern fn rust_begin_panic(info: &PanicInfo) -> ! {
unsafe { intrinsics::abort() }
}
</code></pre>
<p>To override the compiler-inserted <code>main</code> shim, one has to disable it
with <code>#![no_main]</code> and then create the appropriate symbol with the
correct ABI and the correct name, which requires overriding the
compiler's name mangling too:</p>
<pre><code class="language-rust ignore">#![feature(lang_items, core_intrinsics)]
#![feature(start)]
#![no_std]
#![no_main]
use core::intrinsics;
use core::panic::PanicInfo;
// Pull in the system libc library for what crt0.o likely requires.
extern crate libc;
// Entry point for this program.
#[no_mangle] // ensure that this symbol is called `main` in the output
pub extern fn main(_argc: i32, _argv: *const *const u8) -> i32 {
0
}
// These functions are used by the compiler, but not
// for a bare-bones hello world. These are normally
// provided by libstd.
#[lang = "eh_personality"]
#[no_mangle]
pub extern fn rust_eh_personality() {
}
// This function may be needed based on the compilation target.
#[lang = "eh_unwind_resume"]
#[no_mangle]
pub extern fn rust_eh_unwind_resume() {
}
#[lang = "panic_impl"]
#[no_mangle]
pub extern fn rust_begin_panic(info: &PanicInfo) -> ! {
unsafe { intrinsics::abort() }
}
</code></pre>
<p>In many cases, you may need to manually link to the <code>compiler_builtins</code> crate
when building a <code>no_std</code> binary. You may observe this via linker error messages
such as "<code>undefined reference to `__rust_probestack'</code>". Using this crate
also requires enabling the library feature <code>compiler_builtins_lib</code>. You can read
more about this <a href="library-features/compiler-builtins-lib.html">here</a>.</p>
<a class="header" href="print.html#more-about-the-language-items" id="more-about-the-language-items"><h2>More about the language items</h2></a>
<p>The compiler currently makes a few assumptions about symbols which are
available in the executable to call. Normally these functions are provided by
the standard library, but without it you must define your own. These symbols
are called "language items", and they each have an internal name, and then a
signature that an implementation must conform to.</p>
<p>The first of these functions, <code>rust_eh_personality</code>, is used by the failure
mechanisms of the compiler. This is often mapped to GCC's personality function
(see the <a href="https://github.com/rust-lang/rust/blob/master/src/libpanic_unwind/gcc.rs">libstd implementation</a> for more information), but crates
which do not trigger a panic can be assured that this function is never
called. The language item's name is <code>eh_personality</code>.</p>
<p>The second function, <code>rust_begin_panic</code>, is also used by the failure mechanisms of the
compiler. When a panic happens, this controls the message that's displayed on
the screen. While the language item's name is <code>panic_impl</code>, the symbol name is
<code>rust_begin_panic</code>.</p>
<p>A third function, <code>rust_eh_unwind_resume</code>, is also needed if the <code>custom_unwind_resume</code>
flag is set in the options of the compilation target. It allows customizing the
process of resuming unwind at the end of the landing pads. The language item's name
is <code>eh_unwind_resume</code>.</p>
<a class="header" href="print.html#list-of-all-language-items" id="list-of-all-language-items"><h2>List of all language items</h2></a>
<p>This is a list of all language items in Rust along with where they are located in
the source code.</p>
<ul>
<li>Primitives
<ul>
<li><code>i8</code>: <code>libcore/num/mod.rs</code></li>
<li><code>i16</code>: <code>libcore/num/mod.rs</code></li>
<li><code>i32</code>: <code>libcore/num/mod.rs</code></li>
<li><code>i64</code>: <code>libcore/num/mod.rs</code></li>
<li><code>i128</code>: <code>libcore/num/mod.rs</code></li>
<li><code>isize</code>: <code>libcore/num/mod.rs</code></li>
<li><code>u8</code>: <code>libcore/num/mod.rs</code></li>
<li><code>u16</code>: <code>libcore/num/mod.rs</code></li>
<li><code>u32</code>: <code>libcore/num/mod.rs</code></li>
<li><code>u64</code>: <code>libcore/num/mod.rs</code></li>
<li><code>u128</code>: <code>libcore/num/mod.rs</code></li>
<li><code>usize</code>: <code>libcore/num/mod.rs</code></li>
<li><code>f32</code>: <code>libstd/f32.rs</code></li>
<li><code>f64</code>: <code>libstd/f64.rs</code></li>
<li><code>char</code>: <code>libcore/char.rs</code></li>
<li><code>slice</code>: <code>liballoc/slice.rs</code></li>
<li><code>str</code>: <code>liballoc/str.rs</code></li>
<li><code>const_ptr</code>: <code>libcore/ptr.rs</code></li>
<li><code>mut_ptr</code>: <code>libcore/ptr.rs</code></li>
<li><code>unsafe_cell</code>: <code>libcore/cell.rs</code></li>
</ul>
</li>
<li>Runtime
<ul>
<li><code>start</code>: <code>libstd/rt.rs</code></li>
<li><code>eh_personality</code>: <code>libpanic_unwind/emcc.rs</code> (EMCC)</li>
<li><code>eh_personality</code>: <code>libpanic_unwind/seh64_gnu.rs</code> (SEH64 GNU)</li>
<li><code>eh_personality</code>: <code>libpanic_unwind/seh.rs</code> (SEH)</li>
<li><code>eh_unwind_resume</code>: <code>libpanic_unwind/seh64_gnu.rs</code> (SEH64 GNU)</li>
<li><code>eh_unwind_resume</code>: <code>libpanic_unwind/gcc.rs</code> (GCC)</li>
<li><code>msvc_try_filter</code>: <code>libpanic_unwind/seh.rs</code> (SEH)</li>
<li><code>panic</code>: <code>libcore/panicking.rs</code></li>
<li><code>panic_bounds_check</code>: <code>libcore/panicking.rs</code></li>
<li><code>panic_impl</code>: <code>libcore/panicking.rs</code></li>
<li><code>panic_impl</code>: <code>libstd/panicking.rs</code></li>
</ul>
</li>
<li>Allocations
<ul>
<li><code>owned_box</code>: <code>liballoc/boxed.rs</code></li>
<li><code>exchange_malloc</code>: <code>liballoc/heap.rs</code></li>
<li><code>box_free</code>: <code>liballoc/heap.rs</code></li>
</ul>
</li>
<li>Operands
<ul>
<li><code>not</code>: <code>libcore/ops/bit.rs</code></li>
<li><code>bitand</code>: <code>libcore/ops/bit.rs</code></li>
<li><code>bitor</code>: <code>libcore/ops/bit.rs</code></li>
<li><code>bitxor</code>: <code>libcore/ops/bit.rs</code></li>
<li><code>shl</code>: <code>libcore/ops/bit.rs</code></li>
<li><code>shr</code>: <code>libcore/ops/bit.rs</code></li>
<li><code>bitand_assign</code>: <code>libcore/ops/bit.rs</code></li>
<li><code>bitor_assign</code>: <code>libcore/ops/bit.rs</code></li>
<li><code>bitxor_assign</code>: <code>libcore/ops/bit.rs</code></li>
<li><code>shl_assign</code>: <code>libcore/ops/bit.rs</code></li>
<li><code>shr_assign</code>: <code>libcore/ops/bit.rs</code></li>
<li><code>deref</code>: <code>libcore/ops/deref.rs</code></li>
<li><code>deref_mut</code>: <code>libcore/ops/deref.rs</code></li>
<li><code>index</code>: <code>libcore/ops/index.rs</code></li>
<li><code>index_mut</code>: <code>libcore/ops/index.rs</code></li>
<li><code>add</code>: <code>libcore/ops/arith.rs</code></li>
<li><code>sub</code>: <code>libcore/ops/arith.rs</code></li>
<li><code>mul</code>: <code>libcore/ops/arith.rs</code></li>
<li><code>div</code>: <code>libcore/ops/arith.rs</code></li>
<li><code>rem</code>: <code>libcore/ops/arith.rs</code></li>
<li><code>neg</code>: <code>libcore/ops/arith.rs</code></li>
<li><code>add_assign</code>: <code>libcore/ops/arith.rs</code></li>
<li><code>sub_assign</code>: <code>libcore/ops/arith.rs</code></li>
<li><code>mul_assign</code>: <code>libcore/ops/arith.rs</code></li>
<li><code>div_assign</code>: <code>libcore/ops/arith.rs</code></li>
<li><code>rem_assign</code>: <code>libcore/ops/arith.rs</code></li>
<li><code>eq</code>: <code>libcore/cmp.rs</code></li>
<li><code>ord</code>: <code>libcore/cmp.rs</code></li>
</ul>
</li>
<li>Functions
<ul>
<li><code>fn</code>: <code>libcore/ops/function.rs</code></li>
<li><code>fn_mut</code>: <code>libcore/ops/function.rs</code></li>
<li><code>fn_once</code>: <code>libcore/ops/function.rs</code></li>
<li><code>generator_state</code>: <code>libcore/ops/generator.rs</code></li>
<li><code>generator</code>: <code>libcore/ops/generator.rs</code></li>
</ul>
</li>
<li>Other
<ul>
<li><code>coerce_unsized</code>: <code>libcore/ops/unsize.rs</code></li>
<li><code>drop</code>: <code>libcore/ops/drop.rs</code></li>
<li><code>drop_in_place</code>: <code>libcore/ptr.rs</code></li>
<li><code>clone</code>: <code>libcore/clone.rs</code></li>
<li><code>copy</code>: <code>libcore/marker.rs</code></li>
<li><code>send</code>: <code>libcore/marker.rs</code></li>
<li><code>sized</code>: <code>libcore/marker.rs</code></li>
<li><code>unsize</code>: <code>libcore/marker.rs</code></li>
<li><code>sync</code>: <code>libcore/marker.rs</code></li>
<li><code>phantom_data</code>: <code>libcore/marker.rs</code></li>
<li><code>freeze</code>: <code>libcore/marker.rs</code></li>
<li><code>debug_trait</code>: <code>libcore/fmt/mod.rs</code></li>
<li><code>non_zero</code>: <code>libcore/nonzero.rs</code></li>
</ul>
</li>
</ul>
<a class="header" href="print.html#link_args" id="link_args"><h1><code>link_args</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/29596">#29596</a></p>
<hr />
<p>You can tell <code>rustc</code> how to customize linking, and that is via the <code>link_args</code>
attribute. This attribute is applied to <code>extern</code> blocks and specifies raw flags
which need to get passed to the linker when producing an artifact. An example
usage would be:</p>
<pre><pre class="playpen"><code class="language-rust no_run">#![feature(link_args)]
#[link_args = "-foo -bar -baz"]
extern {}
# fn main() {}
</code></pre></pre>
<p>Note that this feature is currently hidden behind the <code>feature(link_args)</code> gate
because this is not a sanctioned way of performing linking. Right now <code>rustc</code>
shells out to the system linker (<code>gcc</code> on most systems, <code>link.exe</code> on MSVC), so
it makes sense to provide extra command line arguments, but this will not
always be the case. In the future <code>rustc</code> may use LLVM directly to link native
libraries, in which case <code>link_args</code> will have no meaning. You can achieve the
same effect as the <code>link_args</code> attribute with the <code>-C link-args</code> argument to
<code>rustc</code>.</p>
<p>It is highly recommended to <em>not</em> use this attribute, and rather use the more
formal <code>#[link(...)]</code> attribute on <code>extern</code> blocks instead.</p>
<a class="header" href="print.html#link_cfg" id="link_cfg"><h1><code>link_cfg</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/37406">#37406</a></p>
<hr />
<a class="header" href="print.html#link_llvm_intrinsics" id="link_llvm_intrinsics"><h1><code>link_llvm_intrinsics</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/29602">#29602</a></p>
<hr />
<a class="header" href="print.html#linkage" id="linkage"><h1><code>linkage</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/29603">#29603</a></p>
<hr />
<a class="header" href="print.html#log_syntax" id="log_syntax"><h1><code>log_syntax</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/29598">#29598</a></p>
<hr />
<a class="header" href="print.html#macro_at_most_once_rep" id="macro_at_most_once_rep"><h1><code>macro_at_most_once_rep</code></h1></a>
<p>The tracking issue for this feature is: TODO(mark-i-m)</p>
<p>With this feature gate enabled, one can use <code>?</code> as a Kleene operator meaning "0
or 1 repetitions" in a macro definition. Previously only <code>+</code> and <code>*</code> were allowed.</p>
<p>For example:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#![feature(macro_at_most_once_rep)]
#fn main() {
macro_rules! foo {
(something $(,)?) // `?` indicates `,` is "optional"...
=> {}
}
#}</code></pre></pre>
<hr />
<a class="header" href="print.html#macro_literal_matcher" id="macro_literal_matcher"><h1><code>macro_literal_matcher</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/35625">#35625</a></p>
<p>The RFC is: <a href="http://rust-lang.github.io/rfcs/1576-macros-literal-matcher.html">rfc#1576</a>.</p>
<p>With this feature gate enabled, the <a href="../book/first-edition/macros.html#syntactic-requirements">list of fragment specifiers</a> gains one more entry:</p>
<ul>
<li><code>literal</code>: a literal. Examples: 2, "string", 'c'</li>
</ul>
<p>A <code>literal</code> may be followed by anything, similarly to the <code>ident</code> specifier.</p>
<hr />
<a class="header" href="print.html#macro_vis_matcher" id="macro_vis_matcher"><h1><code>macro_vis_matcher</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/41022">#41022</a></p>
<p>With this feature gate enabled, the <a href="../book/first-edition/macros.html#syntactic-requirements">list of fragment specifiers</a> gains one more entry:</p>
<ul>
<li><code>vis</code>: a visibility qualifier. Examples: nothing (default visibility); <code>pub</code>; <code>pub(crate)</code>.</li>
</ul>
<p>A <code>vis</code> variable may be followed by a comma, ident, type, or path.</p>
<hr />
<a class="header" href="print.html#macros_in_extern" id="macros_in_extern"><h1><code>macros_in_extern</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/49476">#49476</a></p>
<hr />
<a class="header" href="print.html#main" id="main"><h1><code>main</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/29634">#29634</a></p>
<hr />
<a class="header" href="print.html#mips_target_feature" id="mips_target_feature"><h1><code>mips_target_feature</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/44839">#44839</a></p>
<hr />
<a class="header" href="print.html#mmx_target_feature" id="mmx_target_feature"><h1><code>mmx_target_feature</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/44839">#44839</a></p>
<hr />
<a class="header" href="print.html#naked_functions" id="naked_functions"><h1><code>naked_functions</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/32408">#32408</a></p>
<hr />
<a class="header" href="print.html#needs_allocator" id="needs_allocator"><h1><code>needs_allocator</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/27389">#27389</a></p>
<hr />
<a class="header" href="print.html#needs_panic_runtime" id="needs_panic_runtime"><h1><code>needs_panic_runtime</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/32837">#32837</a></p>
<hr />
<a class="header" href="print.html#never_type" id="never_type"><h1><code>never_type</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/35121">#35121</a></p>
<hr />
<a class="header" href="print.html#nll" id="nll"><h1><code>nll</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/43234">#43234</a></p>
<hr />
<a class="header" href="print.html#no_core" id="no_core"><h1><code>no_core</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/29639">#29639</a></p>
<hr />
<a class="header" href="print.html#no_debug" id="no_debug"><h1><code>no_debug</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/29721">#29721</a></p>
<hr />
<a class="header" href="print.html#non_ascii_idents" id="non_ascii_idents"><h1><code>non_ascii_idents</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/28979">#28979</a></p>
<hr />
<p>The <code>non_ascii_idents</code> feature adds support for non-ASCII identifiers.</p>
<a class="header" href="print.html#examples-3" id="examples-3"><h2>Examples</h2></a>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#![feature(non_ascii_idents)]
#fn main() {
const ε: f64 = 0.00001f64;
const Î : f64 = 3.14f64;
#}</code></pre></pre>
<a class="header" href="print.html#changes-to-the-language-reference" id="changes-to-the-language-reference"><h2>Changes to the language reference</h2></a>
<blockquote>
<p><strong><sup>Lexer:<sup></strong><br />
IDENTIFIER :<br />
    XID_start XID_continue<sup>*</sup><br />
  | <code>_</code> XID_continue<sup>+</sup></p>
</blockquote>
<p>An identifier is any nonempty Unicode string of the following form:</p>
<p>Either</p>
<ul>
<li>The first character has property <a href="http://unicode.org/cldr/utility/list-unicodeset.jsp?a=%5B%3AXID_Start%3A%5D&abb=on&g=&i="><code>XID_start</code></a></li>
<li>The remaining characters have property <a href="http://unicode.org/cldr/utility/list-unicodeset.jsp?a=%5B%3AXID_Continue%3A%5D&abb=on&g=&i="><code>XID_continue</code></a></li>
</ul>
<p>Or</p>
<ul>
<li>The first character is <code>_</code></li>
<li>The identifier is more than one character, <code>_</code> alone is not an identifier</li>
<li>The remaining characters have property <a href="http://unicode.org/cldr/utility/list-unicodeset.jsp?a=%5B%3AXID_Continue%3A%5D&abb=on&g=&i="><code>XID_continue</code></a></li>
</ul>
<p>that does <em>not</em> occur in the set of <a href="../reference/keywords.html#strict-keywords">strict keywords</a>.</p>
<blockquote>
<p><strong>Note</strong>: <a href="http://unicode.org/cldr/utility/list-unicodeset.jsp?a=%5B%3AXID_Start%3A%5D&abb=on&g=&i="><code>XID_start</code></a> and <a href="http://unicode.org/cldr/utility/list-unicodeset.jsp?a=%5B%3AXID_Continue%3A%5D&abb=on&g=&i="><code>XID_continue</code></a> as character properties cover the
character ranges used to form the more familiar C and Java language-family
identifiers.</p>
</blockquote>
<a class="header" href="print.html#non_exhaustive" id="non_exhaustive"><h1><code>non_exhaustive</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/44109">#44109</a></p>
<hr />
<p>The <code>non_exhaustive</code> gate allows you to use the <code>#[non_exhaustive]</code> attribute
on structs and enums. When applied within a crate, users of the crate will need
to use the <code>_</code> pattern when matching enums and use the <code>..</code> pattern when
matching structs. Structs marked as <code>non_exhaustive</code> will not be able to be
created normally outside of the defining crate. This is demonstrated below:</p>
<pre><code class="language-rust ignore(pseudo-Rust)">use std::error::Error as StdError;
#[non_exhaustive]
pub enum Error {
Message(String),
Other,
}
impl StdError for Error {
fn description(&self) -> &str {
// This will not error, despite being marked as non_exhaustive, as this
// enum is defined within the current crate, it can be matched
// exhaustively.
match *self {
Message(ref s) => s,
Other => "other or unknown error",
}
}
}
</code></pre>
<pre><code class="language-rust ignore(pseudo-Rust)">use mycrate::Error;
// This will not error as the non_exhaustive Error enum has been matched with
// a wildcard.
match error {
Message(ref s) => ...,
Other => ...,
_ => ...,
}
</code></pre>
<pre><code class="language-rust ignore(pseudo-Rust)">#[non_exhaustive]
pub struct Config {
pub window_width: u16,
pub window_height: u16,
}
// We can create structs as normal within the defining crate when marked as
// non_exhaustive.
let config = Config { window_width: 640, window_height: 480 };
// We can match structs exhaustively when within the defining crate.
if let Ok(Config { window_width, window_height }) = load_config() {
// ...
}
</code></pre>
<pre><code class="language-rust ignore(pseudo-Rust)">use mycrate::Config;
// We cannot create a struct like normal if it has been marked as
// non_exhaustive.
let config = Config { window_width: 640, window_height: 480 };
// By adding the `..` we can match the config as below outside of the crate
// when marked non_exhaustive.
let &Config { window_width, window_height, .. } = config;
</code></pre>
<a class="header" href="print.html#non_modrs_mods" id="non_modrs_mods"><h1><code>non_modrs_mods</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/44660">#44660</a></p>
<hr />
<a class="header" href="print.html#omit_gdb_pretty_printer_section" id="omit_gdb_pretty_printer_section"><h1><code>omit_gdb_pretty_printer_section</code></h1></a>
<p>This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.</p>
<hr />
<a class="header" href="print.html#on_unimplemented" id="on_unimplemented"><h1><code>on_unimplemented</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/29628">#29628</a></p>
<hr />
<p>The <code>on_unimplemented</code> feature provides the <code>#[rustc_on_unimplemented]</code>
attribute, which allows trait definitions to add specialized notes to error
messages when an implementation was expected but not found.</p>
<p>For example:</p>
<pre><pre class="playpen"><code class="language-rust compile_fail">#![feature(on_unimplemented)]
#[rustc_on_unimplemented="an iterator over elements of type `{A}` \
cannot be built from a collection of type `{Self}`"]
trait MyIterator<A> {
fn next(&mut self) -> A;
}
fn iterate_chars<I: MyIterator<char>>(i: I) {
// ...
}
fn main() {
iterate_chars(&[1, 2, 3][..]);
}
</code></pre></pre>
<p>When the user compiles this, they will see the following;</p>
<pre><code class="language-txt">error[E0277]: the trait bound `&[{integer}]: MyIterator<char>` is not satisfied
--> <anon>:14:5
|
14 | iterate_chars(&[1, 2, 3][..]);
| ^^^^^^^^^^^^^ an iterator over elements of type `char` cannot be built from a collection of type `&[{integer}]`
|
= help: the trait `MyIterator<char>` is not implemented for `&[{integer}]`
= note: required by `iterate_chars`
error: aborting due to previous error
</code></pre>
<a class="header" href="print.html#optin_builtin_traits" id="optin_builtin_traits"><h1><code>optin_builtin_traits</code></h1></a>
<p>The tracking issue for this feature is <a href="https://github.com/rust-lang/rust/issues/13231">#13231</a></p>
<hr />
<p>The <code>optin_builtin_traits</code> feature gate allows you to define auto traits.</p>
<p>Auto traits, like <a href="https://doc.rust-lang.org/std/marker/trait.Send.html"><code>Send</code></a> or <a href="https://doc.rust-lang.org/std/marker/trait.Sync.html"><code>Sync</code></a> in the standard library, are marker traits
that are automatically implemented for every type, unless the type, or a type it contains,
has explicitly opted out via a negative impl.</p>
<pre><code class="language-rust ignore">impl !Type for Trait
</code></pre>
<p>Example:</p>
<pre><pre class="playpen"><code class="language-rust">#![feature(optin_builtin_traits)]
auto trait Valid {}
struct True;
struct False;
impl !Valid for False {}
struct MaybeValid<T>(T);
fn must_be_valid<T: Valid>(_t: T) { }
fn main() {
// works
must_be_valid( MaybeValid(True) );
// compiler error - trait bound not satisfied
// must_be_valid( MaybeValid(False) );
}
</code></pre></pre>
<a class="header" href="print.html#overlapping_marker_traits" id="overlapping_marker_traits"><h1><code>overlapping_marker_traits</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/29864">#29864</a></p>
<hr />
<a class="header" href="print.html#panic_implementation" id="panic_implementation"><h1><code>panic_implementation</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/44489">#44489</a></p>
<hr />
<a class="header" href="print.html#panic_runtime" id="panic_runtime"><h1><code>panic_runtime</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/32837">#32837</a></p>
<hr />
<a class="header" href="print.html#pattern_parentheses" id="pattern_parentheses"><h1><code>pattern_parentheses</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/51087">#51087</a></p>
<hr />
<a class="header" href="print.html#platform_intrinsics" id="platform_intrinsics"><h1><code>platform_intrinsics</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/27731">#27731</a></p>
<hr />
<a class="header" href="print.html#plugin" id="plugin"><h1><code>plugin</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/29597">#29597</a></p>
<p>This feature is part of "compiler plugins." It will often be used with the
<a href="language-features/plugin-registrar.html"><code>plugin_registrar</code></a> and <code>rustc_private</code> features.</p>
<hr />
<p><code>rustc</code> can load compiler plugins, which are user-provided libraries that
extend the compiler's behavior with new syntax extensions, lint checks, etc.</p>
<p>A plugin is a dynamic library crate with a designated <em>registrar</em> function that
registers extensions with <code>rustc</code>. Other crates can load these extensions using
the crate attribute <code>#![plugin(...)]</code>. See the
<code>rustc_plugin</code> documentation for more about the
mechanics of defining and loading a plugin.</p>
<p>If present, arguments passed as <code>#![plugin(foo(... args ...))]</code> are not
interpreted by rustc itself. They are provided to the plugin through the
<code>Registry</code>'s <code>args</code> method.</p>
<p>In the vast majority of cases, a plugin should <em>only</em> be used through
<code>#![plugin]</code> and not through an <code>extern crate</code> item. Linking a plugin would
pull in all of libsyntax and librustc as dependencies of your crate. This is
generally unwanted unless you are building another plugin. The
<code>plugin_as_library</code> lint checks these guidelines.</p>
<p>The usual practice is to put compiler plugins in their own crate, separate from
any <code>macro_rules!</code> macros or ordinary Rust code meant to be used by consumers
of a library.</p>
<a class="header" href="print.html#syntax-extensions" id="syntax-extensions"><h1>Syntax extensions</h1></a>
<p>Plugins can extend Rust's syntax in various ways. One kind of syntax extension
is the procedural macro. These are invoked the same way as <a href="../book/macros.html">ordinary
macros</a>, but the expansion is performed by arbitrary Rust
code that manipulates syntax trees at
compile time.</p>
<p>Let's write a plugin
<a href="https://github.com/rust-lang/rust/blob/master/src/test/run-pass-fulldeps/auxiliary/roman_numerals.rs"><code>roman_numerals.rs</code></a>
that implements Roman numeral integer literals.</p>
<pre><code class="language-rust ignore">#![crate_type="dylib"]
#![feature(plugin_registrar, rustc_private)]
extern crate syntax;
extern crate rustc;
extern crate rustc_plugin;
use syntax::parse::token;
use syntax::tokenstream::TokenTree;
use syntax::ext::base::{ExtCtxt, MacResult, DummyResult, MacEager};
use syntax::ext::build::AstBuilder; // A trait for expr_usize.
use syntax::ext::quote::rt::Span;
use rustc_plugin::Registry;
fn expand_rn(cx: &mut ExtCtxt, sp: Span, args: &[TokenTree])
-> Box<MacResult + 'static> {
static NUMERALS: &'static [(&'static str, usize)] = &[
("M", 1000), ("CM", 900), ("D", 500), ("CD", 400),
("C", 100), ("XC", 90), ("L", 50), ("XL", 40),
("X", 10), ("IX", 9), ("V", 5), ("IV", 4),
("I", 1)];
if args.len() != 1 {
cx.span_err(
sp,
&format!("argument should be a single identifier, but got {} arguments", args.len()));
return DummyResult::any(sp);
}
let text = match args[0] {
TokenTree::Token(_, token::Ident(s)) => s.to_string(),
_ => {
cx.span_err(sp, "argument should be a single identifier");
return DummyResult::any(sp);
}
};
let mut text = &*text;
let mut total = 0;
while !text.is_empty() {
match NUMERALS.iter().find(|&&(rn, _)| text.starts_with(rn)) {
Some(&(rn, val)) => {
total += val;
text = &text[rn.len()..];
}
None => {
cx.span_err(sp, "invalid Roman numeral");
return DummyResult::any(sp);
}
}
}
MacEager::expr(cx.expr_usize(sp, total))
}
#[plugin_registrar]
pub fn plugin_registrar(reg: &mut Registry) {
reg.register_macro("rn", expand_rn);
}
</code></pre>
<p>Then we can use <code>rn!()</code> like any other macro:</p>
<pre><code class="language-rust ignore">#![feature(plugin)]
#![plugin(roman_numerals)]
fn main() {
assert_eq!(rn!(MMXV), 2015);
}
</code></pre>
<p>The advantages over a simple <code>fn(&str) -> u32</code> are:</p>
<ul>
<li>The (arbitrarily complex) conversion is done at compile time.</li>
<li>Input validation is also performed at compile time.</li>
<li>It can be extended to allow use in patterns, which effectively gives
a way to define new literal syntax for any data type.</li>
</ul>
<p>In addition to procedural macros, you can define new
<a href="../reference/attributes.html#derive"><code>derive</code></a>-like attributes and other kinds
of extensions. See <code>Registry::register_syntax_extension</code> and the
<code>SyntaxExtension</code> enum. For a more involved macro example, see
<a href="https://github.com/rust-lang/regex/blob/master/regex_macros/src/lib.rs"><code>regex_macros</code></a>.</p>
<a class="header" href="print.html#tips-and-tricks" id="tips-and-tricks"><h2>Tips and tricks</h2></a>
<p>Some of the <a href="../book/first-edition/macros.html#debugging-macro-code">macro debugging tips</a> are applicable.</p>
<p>You can use <code>syntax::parse</code> to turn token trees into
higher-level syntax elements like expressions:</p>
<pre><code class="language-rust ignore">fn expand_foo(cx: &mut ExtCtxt, sp: Span, args: &[TokenTree])
-> Box<MacResult+'static> {
let mut parser = cx.new_parser_from_tts(args);
let expr: P<Expr> = parser.parse_expr();
</code></pre>
<p>Looking through <a href="https://github.com/rust-lang/rust/blob/master/src/libsyntax/parse/parser.rs"><code>libsyntax</code> parser
code</a>
will give you a feel for how the parsing infrastructure works.</p>
<p>Keep the <code>Span</code>s of everything you parse, for better error reporting. You can
wrap <code>Spanned</code> around your custom data structures.</p>
<p>Calling <code>ExtCtxt::span_fatal</code> will immediately abort compilation. It's better to
instead call <code>ExtCtxt::span_err</code> and return <code>DummyResult</code> so that the compiler
can continue and find further errors.</p>
<p>To print syntax fragments for debugging, you can use <code>span_note</code> together with
<code>syntax::print::pprust::*_to_string</code>.</p>
<p>The example above produced an integer literal using <code>AstBuilder::expr_usize</code>.
As an alternative to the <code>AstBuilder</code> trait, <code>libsyntax</code> provides a set of
quasiquote macros. They are undocumented and very rough around the edges.
However, the implementation may be a good starting point for an improved
quasiquote as an ordinary plugin library.</p>
<a class="header" href="print.html#lint-plugins" id="lint-plugins"><h1>Lint plugins</h1></a>
<p>Plugins can extend <a href="../reference/attributes.html#lint-check-attributes">Rust's lint
infrastructure</a> with
additional checks for code style, safety, etc. Now let's write a plugin
<a href="https://github.com/rust-lang/rust/blob/master/src/test/ui-fulldeps/auxiliary/lint_plugin_test.rs"><code>lint_plugin_test.rs</code></a>
that warns about any item named <code>lintme</code>.</p>
<pre><code class="language-rust ignore">#![feature(plugin_registrar)]
#![feature(box_syntax, rustc_private)]
extern crate syntax;
// Load rustc as a plugin to get macros
#[macro_use]
extern crate rustc;
extern crate rustc_plugin;
use rustc::lint::{EarlyContext, LintContext, LintPass, EarlyLintPass,
EarlyLintPassObject, LintArray};
use rustc_plugin::Registry;
use syntax::ast;
declare_lint!(TEST_LINT, Warn, "Warn about items named 'lintme'");
struct Pass;
impl LintPass for Pass {
fn get_lints(&self) -> LintArray {
lint_array!(TEST_LINT)
}
}
impl EarlyLintPass for Pass {
fn check_item(&mut self, cx: &EarlyContext, it: &ast::Item) {
if it.ident.as_str() == "lintme" {
cx.span_lint(TEST_LINT, it.span, "item is named 'lintme'");
}
}
}
#[plugin_registrar]
pub fn plugin_registrar(reg: &mut Registry) {
reg.register_early_lint_pass(box Pass as EarlyLintPassObject);
}
</code></pre>
<p>Then code like</p>
<pre><code class="language-rust ignore">#![plugin(lint_plugin_test)]
fn lintme() { }
</code></pre>
<p>will produce a compiler warning:</p>
<pre><code class="language-txt">foo.rs:4:1: 4:16 warning: item is named 'lintme', #[warn(test_lint)] on by default
foo.rs:4 fn lintme() { }
^~~~~~~~~~~~~~~
</code></pre>
<p>The components of a lint plugin are:</p>
<ul>
<li>
<p>one or more <code>declare_lint!</code> invocations, which define static <code>Lint</code> structs;</p>
</li>
<li>
<p>a struct holding any state needed by the lint pass (here, none);</p>
</li>
<li>
<p>a <code>LintPass</code>
implementation defining how to check each syntax element. A single
<code>LintPass</code> may call <code>span_lint</code> for several different <code>Lint</code>s, but should
register them all through the <code>get_lints</code> method.</p>
</li>
</ul>
<p>Lint passes are syntax traversals, but they run at a late stage of compilation
where type information is available. <code>rustc</code>'s <a href="https://github.com/rust-lang/rust/blob/master/src/librustc/lint/builtin.rs">built-in
lints</a>
mostly use the same infrastructure as lint plugins, and provide examples of how
to access type information.</p>
<p>Lints defined by plugins are controlled by the usual <a href="../reference/attributes.html#lint-check-attributes">attributes and compiler
flags</a>, e.g.
<code>#[allow(test_lint)]</code> or <code>-A test-lint</code>. These identifiers are derived from the
first argument to <code>declare_lint!</code>, with appropriate case and punctuation
conversion.</p>
<p>You can run <code>rustc -W help foo.rs</code> to see a list of lints known to <code>rustc</code>,
including those provided by plugins loaded by <code>foo.rs</code>.</p>
<a class="header" href="print.html#plugin_registrar" id="plugin_registrar"><h1><code>plugin_registrar</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/29597">#29597</a></p>
<p>This feature is part of "compiler plugins." It will often be used with the
<a href="language-features/plugin.html"><code>plugin</code></a> and <code>rustc_private</code> features as well. For more details, see
their docs.</p>
<hr />
<a class="header" href="print.html#powerpc_target_feature" id="powerpc_target_feature"><h1><code>powerpc_target_feature</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/44839">#44839</a></p>
<hr />
<a class="header" href="print.html#prelude_import" id="prelude_import"><h1><code>prelude_import</code></h1></a>
<p>This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.</p>
<hr />
<a class="header" href="print.html#proc_macro" id="proc_macro"><h1><code>proc_macro</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/38356">#38356</a></p>
<hr />
<p>This feature flag guards the new procedural macro features as laid out by <a href="https://github.com/rust-lang/rfcs/blob/master/text/1566-proc-macros.md">RFC 1566</a>, which alongside the now-stable
<a href="https://doc.rust-lang.org/book/procedural-macros.html">custom derives</a>, provide stabilizable alternatives to the compiler plugin API (which requires the use of
perma-unstable internal APIs) for programmatically modifying Rust code at compile-time.</p>
<p>The two new procedural macro kinds are:</p>
<ul>
<li>
<p>Function-like procedural macros which are invoked like regular declarative macros, and:</p>
</li>
<li>
<p>Attribute-like procedural macros which can be applied to any item which built-in attributes can
be applied to, and which can take arguments in their invocation as well.</p>
</li>
</ul>
<p>Additionally, this feature flag implicitly enables the <a href="language-features/use-extern-macros.html"><code>use_extern_macros</code></a> feature,
which allows macros to be imported like any other item with <code>use</code> statements, as compared to
applying <code>#[macro_use]</code> to an <code>extern crate</code> declaration. It is important to note that procedural macros may
<strong>only</strong> be imported in this manner, and will throw an error otherwise.</p>
<p>You <strong>must</strong> declare the <code>proc_macro</code> feature in both the crate declaring these new procedural macro kinds as well as
in any crates that use them.</p>
<a class="header" href="print.html#common-concepts" id="common-concepts"><h3>Common Concepts</h3></a>
<p>As with custom derives, procedural macros may only be declared in crates of the <code>proc-macro</code> type, and must be public
functions. No other public items may be declared in <code>proc-macro</code> crates, but private items are fine.</p>
<p>To declare your crate as a <code>proc-macro</code> crate, simply add:</p>
<pre><code class="language-toml">[lib]
proc-macro = true
</code></pre>
<p>to your <code>Cargo.toml</code>.</p>
<p>Unlike custom derives, however, the name of the function implementing the procedural macro is used directly as the
procedural macro's name, so choose carefully.</p>
<p>Additionally, both new kinds of procedural macros return a <code>TokenStream</code> which <em>wholly</em> replaces the original
invocation and its input.</p>
<a class="header" href="print.html#importing" id="importing"><h4>Importing</h4></a>
<p>As referenced above, the new procedural macros are not meant to be imported via <code>#[macro_use]</code> and will throw an
error if they are. Instead, they are meant to be imported like any other item in Rust, with <code>use</code> statements:</p>
<pre><code class="language-rust ignore">#![feature(proc_macro)]
// Where `my_proc_macros` is some crate of type `proc_macro`
extern crate my_proc_macros;
// And declares a `#[proc_macro] pub fn my_bang_macro()` at its root.
use my_proc_macros::my_bang_macro;
fn main() {
println!("{}", my_bang_macro!());
}
</code></pre>
<a class="header" href="print.html#error-reporting" id="error-reporting"><h4>Error Reporting</h4></a>
<p>Any panics in a procedural macro implementation will be caught by the compiler and turned into an error message pointing
to the problematic invocation. Thus, it is important to make your panic messages as informative as possible: use
<code>Option::expect</code> instead of <code>Option::unwrap</code> and <code>Result::expect</code> instead of <code>Result::unwrap</code>, and inform the user of
the error condition as unambiguously as you can.</p>
<a class="header" href="print.html#tokenstream" id="tokenstream"><h4><code>TokenStream</code></h4></a>
<p>The <code>proc_macro::TokenStream</code> type is hardcoded into the signatures of procedural macro functions for both input and
output. It is a wrapper around the compiler's internal representation for a given chunk of Rust code.</p>
<a class="header" href="print.html#function-like-procedural-macros" id="function-like-procedural-macros"><h3>Function-like Procedural Macros</h3></a>
<p>These are procedural macros that are invoked like regular declarative macros. They are declared as public functions in
crates of the <code>proc_macro</code> type and using the <code>#[proc_macro]</code> attribute. The name of the declared function becomes the
name of the macro as it is to be imported and used. The function must be of the kind <code>fn(TokenStream) -> TokenStream</code>
where the sole argument is the input to the macro and the return type is the macro's output.</p>
<p>This kind of macro can expand to anything that is valid for the context it is invoked in, including expressions and
statements, as well as items.</p>
<p><strong>Note</strong>: invocations of this kind of macro require a wrapping <code>[]</code>, <code>{}</code> or <code>()</code> like regular macros, but these do not
appear in the input, only the tokens between them. The tokens between the braces do not need to be valid Rust syntax.</p>
<p><span class="filename">my_macro_crate/src/lib.rs</span></p>
<pre><code class="language-rust ignore">#![feature(proc_macro)]
// This is always necessary to get the `TokenStream` typedef.
extern crate proc_macro;
use proc_macro::TokenStream;
#[proc_macro]
pub fn say_hello(_input: TokenStream) -> TokenStream {
// This macro will accept any input because it ignores it.
// To enforce correctness in macros which don't take input,
// you may want to add `assert!(_input.to_string().is_empty());`.
"println!(\"Hello, world!\")".parse().unwrap()
}
</code></pre>
<p><span class="filename">my_macro_user/Cargo.toml</span></p>
<pre><code class="language-toml">[dependencies]
my_macro_crate = { path = "<relative path to my_macro_crate>" }
</code></pre>
<p><span class="filename">my_macro_user/src/lib.rs</span></p>
<pre><code class="language-rust ignore">#![feature(proc_macro)]
extern crate my_macro_crate;
use my_macro_crate::say_hello;
fn main() {
say_hello!();
}
</code></pre>
<p>As expected, this prints <code>Hello, world!</code>.</p>
<a class="header" href="print.html#attribute-like-procedural-macros" id="attribute-like-procedural-macros"><h3>Attribute-like Procedural Macros</h3></a>
<p>These are arguably the most powerful flavor of procedural macro as they can be applied anywhere attributes are allowed.</p>
<p>They are declared as public functions in crates of the <code>proc-macro</code> type, using the <code>#[proc_macro_attribute]</code> attribute.
The name of the function becomes the name of the attribute as it is to be imported and used. The function must be of the
kind <code>fn(TokenStream, TokenStream) -> TokenStream</code> where:</p>
<p>The first argument represents any metadata for the attribute (see <a href="https://doc.rust-lang.org/reference/attributes.html">the reference chapter on attributes</a>).
Only the metadata itself will appear in this argument, for example:</p>
<ul>
<li><code>#[my_macro]</code> will get an empty string.</li>
<li><code>#[my_macro = "string"]</code> will get <code>= "string"</code>.</li>
<li><code>#[my_macro(ident)]</code> will get <code>(ident)</code>.</li>
<li>etc.</li>
</ul>
<p>The second argument is the item that the attribute is applied to. It can be a function, a type definition,
an impl block, an <code>extern</code> block, or a module—attribute invocations can take the inner form (<code>#![my_attr]</code>)
or outer form (<code>#[my_attr]</code>).</p>
<p>The return type is the output of the macro which <em>wholly</em> replaces the item it was applied to. Thus, if your intention
is to merely modify an item, it <em>must</em> be copied to the output. The output must be an item; expressions, statements
and bare blocks are not allowed.</p>
<p>There is no restriction on how many items an attribute-like procedural macro can emit as long as they are valid in
the given context.</p>
<p><span class="filename">my_macro_crate/src/lib.rs</span></p>
<pre><code class="language-rust ignore">#![feature(proc_macro)]
extern crate proc_macro;
use proc_macro::TokenStream;
/// Adds a `/// ### Panics` docstring to the end of the input's documentation
///
/// Does not assert that its receiver is a function or method.
#[proc_macro_attribute]
pub fn panics_note(args: TokenStream, input: TokenStream) -> TokenStream {
let args = args.to_string();
let mut input = input.to_string();
assert!(args.starts_with("= \""), "`#[panics_note]` requires an argument of the form \
`#[panics_note = \"panic note here\"]`");
// Get just the bare note string
let panics_note = args.trim_matches(&['=', ' ', '"'][..]);
// The input will include all docstrings regardless of where the attribute is placed,
// so we need to find the last index before the start of the item
let insert_idx = idx_after_last_docstring(&input);
// And insert our `### Panics` note there so it always appears at the end of an item's docs
input.insert_str(insert_idx, &format!("/// # Panics \n/// {}\n", panics_note));
input.parse().unwrap()
}
// `proc-macro` crates can contain any kind of private item still
fn idx_after_last_docstring(input: &str) -> usize {
// Skip docstring lines to find the start of the item proper
input.lines().skip_while(|line| line.trim_left().starts_with("///")).next()
// Find the index of the first non-docstring line in the input
// Note: assumes this exact line is unique in the input
.and_then(|line_after| input.find(line_after))
// No docstrings in the input
.unwrap_or(0)
}
</code></pre>
<p><span class="filename">my_macro_user/Cargo.toml</span></p>
<pre><code class="language-toml">[dependencies]
my_macro_crate = { path = "<relative path to my_macro_crate>" }
</code></pre>
<p><span class="filename">my_macro_user/src/lib.rs</span></p>
<pre><code class="language-rust ignore">#![feature(proc_macro)]
extern crate my_macro_crate;
use my_macro_crate::panics_note;
/// Do the `foo` thing.
#[panics_note = "Always."]
pub fn foo() {
panic!()
}
</code></pre>
<p>Then the rendered documentation for <code>pub fn foo</code> will look like this:</p>
<blockquote>
<p><code>pub fn foo()</code></p>
<hr />
<p>Do the <code>foo</code> thing.</p>
<a class="header" href="print.html#panics" id="panics"><h1>Panics</h1></a>
<p>Always.</p>
</blockquote>
<a class="header" href="print.html#proc_macro_expr" id="proc_macro_expr"><h1><code>proc_macro_expr</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/38356">#38356</a></p>
<hr />
<a class="header" href="print.html#proc_macro_gen" id="proc_macro_gen"><h1><code>proc_macro_gen</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/38356">#38356</a></p>
<hr />
<a class="header" href="print.html#proc_macro_mod" id="proc_macro_mod"><h1><code>proc_macro_mod</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/38356">#38356</a></p>
<hr />
<a class="header" href="print.html#proc_macro_non_items" id="proc_macro_non_items"><h1><code>proc_macro_non_items</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/38356">#38356</a></p>
<hr />
<a class="header" href="print.html#proc_macro_path_invoc" id="proc_macro_path_invoc"><h1><code>proc_macro_path_invoc</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/38356">#38356</a></p>
<hr />
<a class="header" href="print.html#profiler_runtime" id="profiler_runtime"><h1><code>profiler_runtime</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/42524">#42524</a>.</p>
<hr />
<a class="header" href="print.html#quote" id="quote"><h1><code>quote</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/29601">#29601</a></p>
<hr />
<a class="header" href="print.html#raw_identifiers" id="raw_identifiers"><h1><code>raw_identifiers</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/48589">#48589</a></p>
<hr />
<a class="header" href="print.html#repr_packed" id="repr_packed"><h1><code>repr_packed</code></h1></a>
<p>The tracking issue for this feature is <a href="https://github.com/rust-lang/rust/issues/33158">#33158</a></p>
<hr />
<a class="header" href="print.html#repr_simd" id="repr_simd"><h1><code>repr_simd</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/27731">#27731</a></p>
<hr />
<a class="header" href="print.html#repr128" id="repr128"><h1><code>repr128</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/35118">#35118</a></p>
<hr />
<p>The <code>repr128</code> feature adds support for <code>#[repr(u128)]</code> on <code>enum</code>s.</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#![feature(repr128)]
#fn main() {
#[repr(u128)]
enum Foo {
Bar(u64),
}
#}</code></pre></pre>
<a class="header" href="print.html#rustc_attrs" id="rustc_attrs"><h1><code>rustc_attrs</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/29642">#29642</a></p>
<hr />
<a class="header" href="print.html#rustc_const_unstable" id="rustc_const_unstable"><h1><code>rustc_const_unstable</code></h1></a>
<p>This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.</p>
<hr />
<a class="header" href="print.html#rustc_diagnostic_macros" id="rustc_diagnostic_macros"><h1><code>rustc_diagnostic_macros</code></h1></a>
<p>This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.</p>
<hr />
<a class="header" href="print.html#sanitizer_runtime" id="sanitizer_runtime"><h1><code>sanitizer_runtime</code></h1></a>
<p>This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.</p>
<hr />
<a class="header" href="print.html#simd_ffi" id="simd_ffi"><h1><code>simd_ffi</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/27731">#27731</a></p>
<hr />
<a class="header" href="print.html#slice_patterns" id="slice_patterns"><h1><code>slice_patterns</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/23121">#23121</a></p>
<hr />
<p>The <code>slice_patterns</code> feature gate lets you use <code>..</code> to indicate any number of
elements inside a pattern matching a slice. This wildcard can only be used once
for a given array. If there's an pattern before the <code>..</code>, the subslice will be
matched against that pattern. For example:</p>
<pre><pre class="playpen"><code class="language-rust">#![feature(slice_patterns)]
fn is_symmetric(list: &[u32]) -> bool {
match list {
&[] | &[_] => true,
&[x, ref inside.., y] if x == y => is_symmetric(inside),
&[..] => false,
}
}
fn main() {
let sym = &[0, 1, 4, 2, 4, 1, 0];
assert!(is_symmetric(sym));
let not_sym = &[0, 1, 7, 2, 4, 1, 0];
assert!(!is_symmetric(not_sym));
}
</code></pre></pre>
<a class="header" href="print.html#specialization" id="specialization"><h1><code>specialization</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/31844">#31844</a></p>
<hr />
<a class="header" href="print.html#sse4a_target_feature" id="sse4a_target_feature"><h1><code>sse4a_target_feature</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/44839">#44839</a></p>
<hr />
<a class="header" href="print.html#staged_api" id="staged_api"><h1><code>staged_api</code></h1></a>
<p>This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.</p>
<hr />
<a class="header" href="print.html#start" id="start"><h1><code>start</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/29633">#29633</a></p>
<hr />
<a class="header" href="print.html#static_nobundle" id="static_nobundle"><h1><code>static_nobundle</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/37403">#37403</a></p>
<hr />
<a class="header" href="print.html#stmt_expr_attributes" id="stmt_expr_attributes"><h1><code>stmt_expr_attributes</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/15701">#15701</a></p>
<hr />
<a class="header" href="print.html#structural_match" id="structural_match"><h1><code>structural_match</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/31434">#31434</a></p>
<hr />
<a class="header" href="print.html#tbm_target_feature" id="tbm_target_feature"><h1><code>tbm_target_feature</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/44839">#44839</a></p>
<hr />
<a class="header" href="print.html#thread_local" id="thread_local"><h1><code>thread_local</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/29594">#29594</a></p>
<hr />
<a class="header" href="print.html#tool_attributes" id="tool_attributes"><h1><code>tool_attributes</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/44690">#44690</a></p>
<hr />
<p>Tool attributes let you use scoped attributes to control the behavior
of certain tools.</p>
<p>Currently tool names which can be appear in scoped attributes are restricted to
<code>clippy</code> and <code>rustfmt</code>.</p>
<a class="header" href="print.html#an-example" id="an-example"><h2>An example</h2></a>
<pre><pre class="playpen"><code class="language-rust">#![feature(tool_attributes)]
#[rustfmt::skip]
fn foo() { println!("hello, world"); }
fn main() {
foo();
}
</code></pre></pre>
<a class="header" href="print.html#trace_macros" id="trace_macros"><h1><code>trace_macros</code></h1></a>
<p>The tracking issue for this feature is <a href="https://github.com/rust-lang/rust/issues/29598">#29598</a>.</p>
<hr />
<p>With <code>trace_macros</code> you can trace the expansion of macros in your code.</p>
<a class="header" href="print.html#examples-4" id="examples-4"><h2>Examples</h2></a>
<pre><pre class="playpen"><code class="language-rust">#![feature(trace_macros)]
fn main() {
trace_macros!(true);
println!("Hello, Rust!");
trace_macros!(false);
}
</code></pre></pre>
<p>The <code>cargo build</code> output:</p>
<pre><code class="language-txt">note: trace_macro
--> src/main.rs:5:5
|
5 | println!("Hello, Rust!");
| ^^^^^^^^^^^^^^^^^^^^^^^^^
|
= note: expanding `println! { "Hello, Rust!" }`
= note: to `print ! ( concat ! ( "Hello, Rust!" , "\n" ) )`
= note: expanding `print! { concat ! ( "Hello, Rust!" , "\n" ) }`
= note: to `$crate :: io :: _print ( format_args ! ( concat ! ( "Hello, Rust!" , "\n" ) )
)`
Finished dev [unoptimized + debuginfo] target(s) in 0.60 secs
</code></pre>
<a class="header" href="print.html#trait_alias" id="trait_alias"><h1><code>trait_alias</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/41517">#41517</a></p>
<hr />
<a class="header" href="print.html#trivial_bounds" id="trivial_bounds"><h1><code>trivial_bounds</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/48214">#48214</a></p>
<hr />
<a class="header" href="print.html#type_ascription" id="type_ascription"><h1><code>type_ascription</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/23416">#23416</a></p>
<hr />
<a class="header" href="print.html#unboxed_closures" id="unboxed_closures"><h1><code>unboxed_closures</code></h1></a>
<p>The tracking issue for this feature is <a href="https://github.com/rust-lang/rust/issues/29625">#29625</a></p>
<p>See Also: <a href="library-features/fn-traits.html"><code>fn_traits</code></a></p>
<hr />
<p>The <code>unboxed_closures</code> feature allows you to write functions using the <code>"rust-call"</code> ABI,
required for implementing the <a href="https://doc.rust-lang.org/std/ops/trait.Fn.html"><code>Fn*</code></a> family of traits. <code>"rust-call"</code> functions must have
exactly one (non self) argument, a tuple representing the argument list.</p>
<pre><pre class="playpen"><code class="language-rust">#![feature(unboxed_closures)]
extern "rust-call" fn add_args(args: (u32, u32)) -> u32 {
args.0 + args.1
}
fn main() {}
</code></pre></pre>
<a class="header" href="print.html#underscore_imports" id="underscore_imports"><h1><code>underscore_imports</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/48216">#48216</a></p>
<hr />
<a class="header" href="print.html#unsized_tuple_coercion" id="unsized_tuple_coercion"><h1><code>unsized_tuple_coercion</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/42877">#42877</a></p>
<hr />
<p>This is a part of <a href="https://github.com/rust-lang/rfcs/blob/master/text/0401-coercions.md">RFC0401</a>. According to the RFC, there should be an implementation like this:</p>
<pre><code class="language-rust ignore">impl<..., T, U: ?Sized> Unsized<(..., U)> for (..., T) where T: Unsized<U> {}
</code></pre>
<p>This implementation is currently gated behind <code>#[feature(unsized_tuple_coercion)]</code> to avoid insta-stability. Therefore you can use it like this:</p>
<pre><pre class="playpen"><code class="language-rust">#![feature(unsized_tuple_coercion)]
fn main() {
let x : ([i32; 3], [i32; 3]) = ([1, 2, 3], [4, 5, 6]);
let y : &([i32; 3], [i32]) = &x;
assert_eq!(y.1[0], 4);
}
</code></pre></pre>
<a class="header" href="print.html#untagged_unions" id="untagged_unions"><h1><code>untagged_unions</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/32836">#32836</a></p>
<hr />
<a class="header" href="print.html#unwind_attributes" id="unwind_attributes"><h1><code>unwind_attributes</code></h1></a>
<p>This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.</p>
<hr />
<a class="header" href="print.html#use_extern_macros" id="use_extern_macros"><h1><code>use_extern_macros</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/35896">#35896</a></p>
<hr />
<a class="header" href="print.html#used" id="used"><h1><code>used</code></h1></a>
<p>The tracking issue for this feature
is: <a href="https://github.com/rust-lang/rust/issues/40289">40289</a>.</p>
<hr />
<p>The <code>#[used]</code> attribute can be applied to <code>static</code> variables to prevent the Rust
compiler from optimizing them away even if they appear to be unused by the crate
(appear to be "dead code").</p>
<pre><pre class="playpen"><code class="language-rust">#![feature(used)]
#[used]
static FOO: i32 = 1;
static BAR: i32 = 2;
fn main() {}
</code></pre></pre>
<p>If you compile this program into an object file, you'll see that <code>FOO</code> makes it
to the object file but <code>BAR</code> doesn't. Neither static variable is used by the
program.</p>
<pre><code class="language-text">$ rustc -C opt-level=3 --emit=obj used.rs
$ nm -C used.o
0000000000000000 T main
U std::rt::lang_start
0000000000000000 r used::FOO
0000000000000000 t used::main
</code></pre>
<p>Note that the <em>linker</em> knows nothing about the <code>#[used]</code> attribute and will
remove <code>#[used]</code> symbols if they are not referenced by other parts of the
program:</p>
<pre><code class="language-text">$ rustc -C opt-level=3 used.rs
$ nm -C used | grep FOO
</code></pre>
<p>"This doesn't sound too useful then!" you may think but keep reading.</p>
<p>To preserve the symbols all the way to the final binary, you'll need the
cooperation of the linker. Here's one example:</p>
<p>The ELF standard defines two special sections, <code>.init_array</code> and
<code>.pre_init_array</code>, that may contain function pointers which will be executed
<em>before</em> the <code>main</code> function is invoked. The linker will preserve symbols placed
in these sections (at least when linking programs that target the <code>*-*-linux-*</code>
targets).</p>
<pre><code class="language-rust ignore">#![feature(used)]
extern "C" fn before_main() {
println!("Hello, world!");
}
#[link_section = ".init_array"]
#[used]
static INIT_ARRAY: [extern "C" fn(); 1] = [before_main];
fn main() {}
</code></pre>
<p>So, <code>#[used]</code> and <code>#[link_section]</code> can be combined to obtain "life before
main".</p>
<pre><code class="language-text">$ rustc -C opt-level=3 before-main.rs
$ ./before-main
Hello, world!
</code></pre>
<p>Another example: ARM Cortex-M microcontrollers need their reset handler, a
pointer to the function that will executed right after the microcontroller is
turned on, to be placed near the start of their FLASH memory to boot properly.</p>
<p>This condition can be met using <code>#[used]</code> and <code>#[link_section]</code> plus a linker
script.</p>
<pre><code class="language-rust ignore">#![feature(panic_implementation)]
#![feature(used)]
#![no_main]
#![no_std]
use core::panic::PanicInfo;
extern "C" fn reset_handler() -> ! {
loop {}
}
#[link_section = ".reset_handler"]
#[used]
static RESET_HANDLER: extern "C" fn() -> ! = reset_handler;
#[panic_implementation]
fn panic_impl(info: &PanicInfo) -> ! {
loop {}
}
</code></pre>
<pre><code class="language-text">MEMORY
{
FLASH : ORIGIN = 0x08000000, LENGTH = 128K
RAM : ORIGIN = 0x20000000, LENGTH = 20K
}
SECTIONS
{
.text ORIGIN(FLASH) :
{
/* Vector table */
LONG(ORIGIN(RAM) + LENGTH(RAM)); /* initial SP value */
KEEP(*(.reset_handler));
/* Omitted: The rest of the vector table */
*(.text.*);
} > FLASH
/DISCARD/ :
{
/* Unused unwinding stuff */
*(.ARM.exidx.*)
}
}
</code></pre>
<pre><code class="language-text">$ xargo rustc --target thumbv7m-none-eabi --release -- \
-C link-arg=-Tlink.x -C link-arg=-nostartfiles
$ arm-none-eabi-objdump -Cd target/thumbv7m-none-eabi/release/app
./target/thumbv7m-none-eabi/release/app: file format elf32-littlearm
Disassembly of section .text:
08000000 <app::RESET_HANDLER-0x4>:
8000000: 20005000 .word 0x20005000
08000004 <app::RESET_HANDLER>:
8000004: 08000009 ....
08000008 <app::reset_handler>:
8000008: e7fe b.n 8000008 <app::reset_handler>
</code></pre>
<a class="header" href="print.html#wasm_custom_section" id="wasm_custom_section"><h1><code>wasm_custom_section</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/51088">#51088</a></p>
<hr />
<a class="header" href="print.html#wasm_import_module" id="wasm_import_module"><h1><code>wasm_import_module</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/51088">#51088</a></p>
<hr />
<a class="header" href="print.html#library-features" id="library-features"><h1>Library Features</h1></a>
<a class="header" href="print.html#align_offset" id="align_offset"><h1><code>align_offset</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/44488">#44488</a></p>
<hr />
<a class="header" href="print.html#alloc" id="alloc"><h1><code>alloc</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/27783">#27783</a></p>
<hr />
<a class="header" href="print.html#alloc_error_hook" id="alloc_error_hook"><h1><code>alloc_error_hook</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/51245">#51245</a></p>
<hr />
<a class="header" href="print.html#alloc_internals" id="alloc_internals"><h1><code>alloc_internals</code></h1></a>
<p>This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.</p>
<hr />
<a class="header" href="print.html#alloc_jemalloc" id="alloc_jemalloc"><h1><code>alloc_jemalloc</code></h1></a>
<p>This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.</p>
<hr />
<a class="header" href="print.html#alloc_system" id="alloc_system"><h1><code>alloc_system</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/32838">#32838</a></p>
<hr />
<a class="header" href="print.html#allocator_api" id="allocator_api"><h1><code>allocator_api</code></h1></a>
<p>The tracking issue for this feature is <a href="https://github.com/rust-lang/rust/issues/32838">#32838</a></p>
<hr />
<p>Sometimes you want the memory for one collection to use a different
allocator than the memory for another collection. In this case,
replacing the global allocator is not a workable option. Instead,
you need to pass in an instance of an <code>Alloc</code> to each collection
for which you want a custom allocator.</p>
<p>TBD</p>
<a class="header" href="print.html#array_error_internals" id="array_error_internals"><h1><code>array_error_internals</code></h1></a>
<p>This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.</p>
<hr />
<a class="header" href="print.html#ascii_ctype" id="ascii_ctype"><h1><code>ascii_ctype</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/39658">#39658</a></p>
<hr />
<a class="header" href="print.html#atomic_min_max" id="atomic_min_max"><h1><code>atomic_min_max</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/48655">#48655</a></p>
<hr />
<a class="header" href="print.html#box_into_raw_non_null" id="box_into_raw_non_null"><h1><code>box_into_raw_non_null</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/47336">#47336</a></p>
<hr />
<a class="header" href="print.html#bufreader_buffer" id="bufreader_buffer"><h1><code>bufreader_buffer</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/45323">#45323</a></p>
<hr />
<a class="header" href="print.html#bufreader_is_empty" id="bufreader_is_empty"><h1><code>bufreader_is_empty</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/45323">#45323</a></p>
<hr />
<a class="header" href="print.html#bufreader_seek_relative" id="bufreader_seek_relative"><h1><code>bufreader_seek_relative</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/31100">#31100</a></p>
<hr />
<a class="header" href="print.html#c_void_variant" id="c_void_variant"><h1><code>c_void_variant</code></h1></a>
<p>This feature is internal to the Rust compiler and is not intended for general use.</p>
<hr />
<a class="header" href="print.html#cell_update" id="cell_update"><h1><code>cell_update</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/50186">#50186</a></p>
<hr />
<a class="header" href="print.html#char_error_internals" id="char_error_internals"><h1><code>char_error_internals</code></h1></a>
<p>This feature is internal to the Rust compiler and is not intended for general use.</p>
<hr />
<a class="header" href="print.html#coerce_unsized" id="coerce_unsized"><h1><code>coerce_unsized</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/27732">#27732</a></p>
<hr />
<a class="header" href="print.html#compiler_builtins_lib" id="compiler_builtins_lib"><h1><code>compiler_builtins_lib</code></h1></a>
<p>The tracking issue for this feature is: None.</p>
<hr />
<p>This feature is required to link to the <code>compiler_builtins</code> crate which contains
"compiler intrinsics". Compiler intrinsics are software implementations of basic
operations like multiplication of <code>u64</code>s. These intrinsics are only required on
platforms where these operations don't directly map to a hardware instruction.</p>
<p>You should never need to explicitly link to the <code>compiler_builtins</code> crate when
building "std" programs as <code>compiler_builtins</code> is already in the dependency
graph of <code>std</code>. But you may need it when building <code>no_std</code> <strong>binary</strong> crates. If
you get a <em>linker</em> error like:</p>
<pre><code class="language-text">$PWD/src/main.rs:11: undefined reference to `__aeabi_lmul'
$PWD/src/main.rs:11: undefined reference to `__aeabi_uldivmod'
</code></pre>
<p>That means that you need to link to this crate.</p>
<p>When you link to this crate, make sure it only appears once in your crate
dependency graph. Also, it doesn't matter where in the dependency graph you
place the <code>compiler_builtins</code> crate.</p>
<!-- NOTE(ignore) doctests don't support `no_std` binaries -->
<pre><code class="language-rust ignore">#![feature(compiler_builtins_lib)]
#![no_std]
extern crate compiler_builtins;
</code></pre>
<a class="header" href="print.html#concat_idents_macro" id="concat_idents_macro"><h1><code>concat_idents_macro</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/29599">#29599</a></p>
<hr />
<a class="header" href="print.html#const_int_ops" id="const_int_ops"><h1><code>const_int_ops</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/24111">#24111</a></p>
<hr />
<a class="header" href="print.html#const_manually_drop_new" id="const_manually_drop_new"><h1><code>const_manually_drop_new</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/24111">#24111</a></p>
<hr />
<a class="header" href="print.html#const_slice_as_ptr" id="const_slice_as_ptr"><h1><code>const_slice_as_ptr</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/24111">#24111</a></p>
<hr />
<a class="header" href="print.html#const_slice_len" id="const_slice_len"><h1><code>const_slice_len</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/24111">#24111</a></p>
<hr />
<a class="header" href="print.html#const_str_as_bytes" id="const_str_as_bytes"><h1><code>const_str_as_bytes</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/24111">#24111</a></p>
<hr />
<a class="header" href="print.html#const_str_as_ptr" id="const_str_as_ptr"><h1><code>const_str_as_ptr</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/24111">#24111</a></p>
<hr />
<a class="header" href="print.html#const_str_len" id="const_str_len"><h1><code>const_str_len</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/24111">#24111</a></p>
<hr />
<a class="header" href="print.html#const_string_new" id="const_string_new"><h1><code>const_string_new</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/24111">#24111</a></p>
<hr />
<a class="header" href="print.html#const_type_id" id="const_type_id"><h1><code>const_type_id</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/24111">#24111</a></p>
<hr />
<a class="header" href="print.html#const_vec_new" id="const_vec_new"><h1><code>const_vec_new</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/24111">#24111</a></p>
<hr />
<a class="header" href="print.html#core_intrinsics" id="core_intrinsics"><h1><code>core_intrinsics</code></h1></a>
<p>This feature is internal to the Rust compiler and is not intended for general use.</p>
<hr />
<a class="header" href="print.html#core_panic" id="core_panic"><h1><code>core_panic</code></h1></a>
<p>This feature is internal to the Rust compiler and is not intended for general use.</p>
<hr />
<a class="header" href="print.html#core_panic_info" id="core_panic_info"><h1><code>core_panic_info</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/44489">#44489</a></p>
<hr />
<a class="header" href="print.html#core_private_bignum" id="core_private_bignum"><h1><code>core_private_bignum</code></h1></a>
<p>This feature is internal to the Rust compiler and is not intended for general use.</p>
<hr />
<a class="header" href="print.html#core_private_diy_float" id="core_private_diy_float"><h1><code>core_private_diy_float</code></h1></a>
<p>This feature is internal to the Rust compiler and is not intended for general use.</p>
<hr />
<a class="header" href="print.html#deadline_api" id="deadline_api"><h1><code>deadline_api</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/46316">#46316</a></p>
<hr />
<a class="header" href="print.html#dec2flt" id="dec2flt"><h1><code>dec2flt</code></h1></a>
<p>This feature is internal to the Rust compiler and is not intended for general use.</p>
<hr />
<a class="header" href="print.html#decode_utf8" id="decode_utf8"><h1><code>decode_utf8</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/33906">#33906</a></p>
<hr />
<a class="header" href="print.html#derive_clone_copy" id="derive_clone_copy"><h1><code>derive_clone_copy</code></h1></a>
<p>This feature is internal to the Rust compiler and is not intended for general use.</p>
<hr />
<a class="header" href="print.html#derive_eq" id="derive_eq"><h1><code>derive_eq</code></h1></a>
<p>This feature is internal to the Rust compiler and is not intended for general use.</p>
<hr />
<a class="header" href="print.html#drain_filter" id="drain_filter"><h1><code>drain_filter</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/43244">#43244</a></p>
<hr />
<a class="header" href="print.html#duration_as_u128" id="duration_as_u128"><h1><code>duration_as_u128</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/50202">#50202</a></p>
<hr />
<a class="header" href="print.html#duration_getters" id="duration_getters"><h1><code>duration_getters</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/24111">#24111</a></p>
<hr />
<a class="header" href="print.html#error_type_id" id="error_type_id"><h1><code>error_type_id</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/27745">#27745</a></p>
<hr />
<a class="header" href="print.html#euclidean_division" id="euclidean_division"><h1><code>euclidean_division</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/49048">#49048</a></p>
<hr />
<a class="header" href="print.html#exact_chunks" id="exact_chunks"><h1><code>exact_chunks</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/47115">#47115</a></p>
<hr />
<a class="header" href="print.html#exact_size_is_empty" id="exact_size_is_empty"><h1><code>exact_size_is_empty</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/35428">#35428</a></p>
<hr />
<a class="header" href="print.html#extra_log_consts" id="extra_log_consts"><h1><code>extra_log_consts</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/50540">#50540</a></p>
<hr />
<a class="header" href="print.html#fd" id="fd"><h1><code>fd</code></h1></a>
<p>This feature is internal to the Rust compiler and is not intended for general use.</p>
<hr />
<a class="header" href="print.html#fd_read" id="fd_read"><h1><code>fd_read</code></h1></a>
<p>This feature is internal to the Rust compiler and is not intended for general use.</p>
<hr />
<a class="header" href="print.html#fixed_size_array" id="fixed_size_array"><h1><code>fixed_size_array</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/27778">#27778</a></p>
<hr />
<a class="header" href="print.html#flt2dec" id="flt2dec"><h1><code>flt2dec</code></h1></a>
<p>This feature is internal to the Rust compiler and is not intended for general use.</p>
<hr />
<a class="header" href="print.html#fmt_internals" id="fmt_internals"><h1><code>fmt_internals</code></h1></a>
<p>This feature is internal to the Rust compiler and is not intended for general use.</p>
<hr />
<a class="header" href="print.html#fn_traits" id="fn_traits"><h1><code>fn_traits</code></h1></a>
<p>The tracking issue for this feature is <a href="https://github.com/rust-lang/rust/issues/29625">#29625</a></p>
<p>See Also: <a href="language-features/unboxed-closures.html"><code>unboxed_closures</code></a></p>
<hr />
<p>The <code>fn_traits</code> feature allows for implementation of the <a href="https://doc.rust-lang.org/std/ops/trait.Fn.html"><code>Fn*</code></a> traits
for creating custom closure-like types.</p>
<pre><pre class="playpen"><code class="language-rust">#![feature(unboxed_closures)]
#![feature(fn_traits)]
struct Adder {
a: u32
}
impl FnOnce<(u32, )> for Adder {
type Output = u32;
extern "rust-call" fn call_once(self, b: (u32, )) -> Self::Output {
self.a + b.0
}
}
fn main() {
let adder = Adder { a: 3 };
assert_eq!(adder(2), 5);
}
</code></pre></pre>
<a class="header" href="print.html#fnbox" id="fnbox"><h1><code>fnbox</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/28796">#28796</a></p>
<hr />
<a class="header" href="print.html#future_atomic_orderings" id="future_atomic_orderings"><h1><code>future_atomic_orderings</code></h1></a>
<p>This feature is internal to the Rust compiler and is not intended for general use.</p>
<hr />
<a class="header" href="print.html#futures_api" id="futures_api"><h1><code>futures_api</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/50547">#50547</a></p>
<hr />
<a class="header" href="print.html#generator_trait" id="generator_trait"><h1><code>generator_trait</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/43122">#43122</a></p>
<hr />
<a class="header" href="print.html#get_type_id" id="get_type_id"><h1><code>get_type_id</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/27745">#27745</a></p>
<hr />
<a class="header" href="print.html#hashmap_internals" id="hashmap_internals"><h1><code>hashmap_internals</code></h1></a>
<p>This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.</p>
<hr />
<a class="header" href="print.html#int_error_internals" id="int_error_internals"><h1><code>int_error_internals</code></h1></a>
<p>This feature is internal to the Rust compiler and is not intended for general use.</p>
<hr />
<a class="header" href="print.html#int_to_from_bytes" id="int_to_from_bytes"><h1><code>int_to_from_bytes</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/49792">#49792</a></p>
<hr />
<a class="header" href="print.html#integer_atomics" id="integer_atomics"><h1><code>integer_atomics</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/32976">#32976</a></p>
<hr />
<a class="header" href="print.html#io" id="io"><h1><code>io</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/27802">#27802</a></p>
<hr />
<a class="header" href="print.html#io_error_internals" id="io_error_internals"><h1><code>io_error_internals</code></h1></a>
<p>This feature is internal to the Rust compiler and is not intended for general use.</p>
<hr />
<a class="header" href="print.html#ip" id="ip"><h1><code>ip</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/27709">#27709</a></p>
<hr />
<a class="header" href="print.html#ip_constructors" id="ip_constructors"><h1><code>ip_constructors</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/44582">#44582</a></p>
<hr />
<a class="header" href="print.html#iterator_find_map" id="iterator_find_map"><h1><code>iterator_find_map</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/49602">#49602</a></p>
<hr />
<a class="header" href="print.html#iterator_flatten" id="iterator_flatten"><h1><code>iterator_flatten</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/48213">#48213</a></p>
<hr />
<a class="header" href="print.html#libstd_io_internals" id="libstd_io_internals"><h1><code>libstd_io_internals</code></h1></a>
<p>This feature is internal to the Rust compiler and is not intended for general use.</p>
<hr />
<a class="header" href="print.html#libstd_sys_internals" id="libstd_sys_internals"><h1><code>libstd_sys_internals</code></h1></a>
<p>This feature is internal to the Rust compiler and is not intended for general use.</p>
<hr />
<a class="header" href="print.html#libstd_thread_internals" id="libstd_thread_internals"><h1><code>libstd_thread_internals</code></h1></a>
<p>This feature is internal to the Rust compiler and is not intended for general use.</p>
<hr />
<a class="header" href="print.html#linked_list_extras" id="linked_list_extras"><h1><code>linked_list_extras</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/27794">#27794</a></p>
<hr />
<a class="header" href="print.html#map_entry_replace" id="map_entry_replace"><h1><code>map_entry_replace</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/44286">#44286</a></p>
<hr />
<a class="header" href="print.html#map_get_key_value" id="map_get_key_value"><h1><code>map_get_key_value</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/49347">#49347</a></p>
<hr />
<a class="header" href="print.html#mpsc_select" id="mpsc_select"><h1><code>mpsc_select</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/27800">#27800</a></p>
<hr />
<a class="header" href="print.html#n16" id="n16"><h1><code>n16</code></h1></a>
<p>This feature is internal to the Rust compiler and is not intended for general use.</p>
<hr />
<a class="header" href="print.html#no_more_cas" id="no_more_cas"><h1><code>no_more_cas</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/48655">#48655</a></p>
<hr />
<a class="header" href="print.html#no_panic_pow" id="no_panic_pow"><h1><code>no_panic_pow</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/48320">#48320</a></p>
<hr />
<a class="header" href="print.html#offset_to" id="offset_to"><h1><code>offset_to</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/41079">#41079</a></p>
<hr />
<a class="header" href="print.html#once_poison" id="once_poison"><h1><code>once_poison</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/33577">#33577</a></p>
<hr />
<a class="header" href="print.html#option_xor" id="option_xor"><h1><code>option_xor</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/50512">#50512</a></p>
<hr />
<a class="header" href="print.html#panic_abort" id="panic_abort"><h1><code>panic_abort</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/32837">#32837</a></p>
<hr />
<a class="header" href="print.html#panic_info_message" id="panic_info_message"><h1><code>panic_info_message</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/44489">#44489</a></p>
<hr />
<a class="header" href="print.html#panic_internals" id="panic_internals"><h1><code>panic_internals</code></h1></a>
<p>This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.</p>
<hr />
<a class="header" href="print.html#panic_unwind" id="panic_unwind"><h1><code>panic_unwind</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/32837">#32837</a></p>
<hr />
<a class="header" href="print.html#pattern" id="pattern"><h1><code>pattern</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/27721">#27721</a></p>
<hr />
<a class="header" href="print.html#pin" id="pin"><h1><code>pin</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/49150">#49150</a></p>
<hr />
<a class="header" href="print.html#print_internals" id="print_internals"><h1><code>print_internals</code></h1></a>
<p>This feature is internal to the Rust compiler and is not intended for general use.</p>
<hr />
<a class="header" href="print.html#proc_macro_internals" id="proc_macro_internals"><h1><code>proc_macro_internals</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/27812">#27812</a></p>
<hr />
<a class="header" href="print.html#process_exitcode_placeholder" id="process_exitcode_placeholder"><h1><code>process_exitcode_placeholder</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/48711">#48711</a></p>
<hr />
<a class="header" href="print.html#process_internals" id="process_internals"><h1><code>process_internals</code></h1></a>
<p>This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.</p>
<hr />
<a class="header" href="print.html#profiler_runtime_lib" id="profiler_runtime_lib"><h1><code>profiler_runtime_lib</code></h1></a>
<p>This feature is internal to the Rust compiler and is not intended for general use.</p>
<hr />
<a class="header" href="print.html#ptr_internals" id="ptr_internals"><h1><code>ptr_internals</code></h1></a>
<p>This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.</p>
<hr />
<a class="header" href="print.html#ptr_offset_from" id="ptr_offset_from"><h1><code>ptr_offset_from</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/41079">#41079</a></p>
<hr />
<a class="header" href="print.html#ptr_wrapping_offset_from" id="ptr_wrapping_offset_from"><h1><code>ptr_wrapping_offset_from</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/41079">#41079</a></p>
<hr />
<a class="header" href="print.html#range_contains" id="range_contains"><h1><code>range_contains</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/32311">#32311</a></p>
<hr />
<a class="header" href="print.html#range_is_empty" id="range_is_empty"><h1><code>range_is_empty</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/48111">#48111</a></p>
<hr />
<a class="header" href="print.html#raw" id="raw"><h1><code>raw</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/27751">#27751</a></p>
<hr />
<a class="header" href="print.html#rc_downcast" id="rc_downcast"><h1><code>rc_downcast</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/44608">#44608</a></p>
<hr />
<a class="header" href="print.html#read_initializer" id="read_initializer"><h1><code>read_initializer</code></h1></a>
<p>The tracking issue for this feature is: [#42788]</p>
<hr />
<a class="header" href="print.html#refcell_map_split" id="refcell_map_split"><h1><code>refcell_map_split</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/51476">#51476</a></p>
<hr />
<a class="header" href="print.html#refcell_replace_swap" id="refcell_replace_swap"><h1><code>refcell_replace_swap</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/43570">#43570</a></p>
<hr />
<a class="header" href="print.html#repeat_generic_slice" id="repeat_generic_slice"><h1><code>repeat_generic_slice</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/48784">#48784</a></p>
<hr />
<a class="header" href="print.html#reverse_bits" id="reverse_bits"><h1><code>reverse_bits</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/48763">#48763</a></p>
<hr />
<a class="header" href="print.html#rt" id="rt"><h1><code>rt</code></h1></a>
<p>This feature is internal to the Rust compiler and is not intended for general use.</p>
<hr />
<a class="header" href="print.html#rustc_private" id="rustc_private"><h1><code>rustc_private</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/27812">#27812</a></p>
<hr />
<a class="header" href="print.html#rustc_stack_internals" id="rustc_stack_internals"><h1><code>rustc_stack_internals</code></h1></a>
<p>This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.</p>
<hr />
<a class="header" href="print.html#sanitizer_runtime_lib" id="sanitizer_runtime_lib"><h1><code>sanitizer_runtime_lib</code></h1></a>
<p>This feature is internal to the Rust compiler and is not intended for general use.</p>
<hr />
<a class="header" href="print.html#set_stdio" id="set_stdio"><h1><code>set_stdio</code></h1></a>
<p>This feature is internal to the Rust compiler and is not intended for general use.</p>
<hr />
<a class="header" href="print.html#shrink_to" id="shrink_to"><h1><code>shrink_to</code></h1></a>
<p>This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.</p>
<hr />
<a class="header" href="print.html#slice_align_to" id="slice_align_to"><h1><code>slice_align_to</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/44488">#44488</a></p>
<hr />
<a class="header" href="print.html#slice_concat_ext" id="slice_concat_ext"><h1><code>slice_concat_ext</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/27747">#27747</a></p>
<hr />
<a class="header" href="print.html#slice_index_methods" id="slice_index_methods"><h1><code>slice_index_methods</code></h1></a>
<p>This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.</p>
<hr />
<a class="header" href="print.html#slice_internals" id="slice_internals"><h1><code>slice_internals</code></h1></a>
<p>This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.</p>
<hr />
<a class="header" href="print.html#slice_sort_by_cached_key" id="slice_sort_by_cached_key"><h1><code>slice_sort_by_cached_key</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/34447">#34447</a></p>
<hr />
<a class="header" href="print.html#sort_internals" id="sort_internals"><h1><code>sort_internals</code></h1></a>
<p>This feature is internal to the Rust compiler and is not intended for general use.</p>
<hr />
<a class="header" href="print.html#std_internals" id="std_internals"><h1><code>std_internals</code></h1></a>
<p>This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.</p>
<hr />
<a class="header" href="print.html#stdsimd" id="stdsimd"><h1><code>stdsimd</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/48556">#48556</a></p>
<hr />
<a class="header" href="print.html#step_trait" id="step_trait"><h1><code>step_trait</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/42168">#42168</a></p>
<hr />
<a class="header" href="print.html#str_escape" id="str_escape"><h1><code>str_escape</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/27791">#27791</a></p>
<hr />
<a class="header" href="print.html#str_internals" id="str_internals"><h1><code>str_internals</code></h1></a>
<p>This feature is internal to the Rust compiler and is not intended for general use.</p>
<hr />
<a class="header" href="print.html#termination_trait_lib" id="termination_trait_lib"><h1><code>termination_trait_lib</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/43301">#43301</a></p>
<hr />
<a class="header" href="print.html#test" id="test"><h1><code>test</code></h1></a>
<p>The tracking issue for this feature is: None.</p>
<hr />
<p>The internals of the <code>test</code> crate are unstable, behind the <code>test</code> flag. The
most widely used part of the <code>test</code> crate are benchmark tests, which can test
the performance of your code. Let's make our <code>src/lib.rs</code> look like this
(comments elided):</p>
<pre><code class="language-rust ignore">#![feature(test)]
extern crate test;
pub fn add_two(a: i32) -> i32 {
a + 2
}
#[cfg(test)]
mod tests {
use super::*;
use test::Bencher;
#[test]
fn it_works() {
assert_eq!(4, add_two(2));
}
#[bench]
fn bench_add_two(b: &mut Bencher) {
b.iter(|| add_two(2));
}
}
</code></pre>
<p>Note the <code>test</code> feature gate, which enables this unstable feature.</p>
<p>We've imported the <code>test</code> crate, which contains our benchmarking support.
We have a new function as well, with the <code>bench</code> attribute. Unlike regular
tests, which take no arguments, benchmark tests take a <code>&mut Bencher</code>. This
<code>Bencher</code> provides an <code>iter</code> method, which takes a closure. This closure
contains the code we'd like to benchmark.</p>
<p>We can run benchmark tests with <code>cargo bench</code>:</p>
<pre><code class="language-bash">$ cargo bench
Compiling adder v0.0.1 (file:///home/steve/tmp/adder)
Running target/release/adder-91b3e234d4ed382a
running 2 tests
test tests::it_works ... ignored
test tests::bench_add_two ... bench: 1 ns/iter (+/- 0)
test result: ok. 0 passed; 0 failed; 1 ignored; 1 measured
</code></pre>
<p>Our non-benchmark test was ignored. You may have noticed that <code>cargo bench</code>
takes a bit longer than <code>cargo test</code>. This is because Rust runs our benchmark
a number of times, and then takes the average. Because we're doing so little
work in this example, we have a <code>1 ns/iter (+/- 0)</code>, but this would show
the variance if there was one.</p>
<p>Advice on writing benchmarks:</p>
<ul>
<li>Move setup code outside the <code>iter</code> loop; only put the part you want to measure inside</li>
<li>Make the code do "the same thing" on each iteration; do not accumulate or change state</li>
<li>Make the outer function idempotent too; the benchmark runner is likely to run
it many times</li>
<li>Make the inner <code>iter</code> loop short and fast so benchmark runs are fast and the
calibrator can adjust the run-length at fine resolution</li>
<li>Make the code in the <code>iter</code> loop do something simple, to assist in pinpointing
performance improvements (or regressions)</li>
</ul>
<a class="header" href="print.html#gotcha-optimizations" id="gotcha-optimizations"><h2>Gotcha: optimizations</h2></a>
<p>There's another tricky part to writing benchmarks: benchmarks compiled with
optimizations activated can be dramatically changed by the optimizer so that
the benchmark is no longer benchmarking what one expects. For example, the
compiler might recognize that some calculation has no external effects and
remove it entirely.</p>
<pre><code class="language-rust ignore">#![feature(test)]
extern crate test;
use test::Bencher;
#[bench]
fn bench_xor_1000_ints(b: &mut Bencher) {
b.iter(|| {
(0..1000).fold(0, |old, new| old ^ new);
});
}
</code></pre>
<p>gives the following results</p>
<pre><code class="language-text">running 1 test
test bench_xor_1000_ints ... bench: 0 ns/iter (+/- 0)
test result: ok. 0 passed; 0 failed; 0 ignored; 1 measured
</code></pre>
<p>The benchmarking runner offers two ways to avoid this. Either, the closure that
the <code>iter</code> method receives can return an arbitrary value which forces the
optimizer to consider the result used and ensures it cannot remove the
computation entirely. This could be done for the example above by adjusting the
<code>b.iter</code> call to</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
# struct X;
# impl X { fn iter<T, F>(&self, _: F) where F: FnMut() -> T {} } let b = X;
b.iter(|| {
// Note lack of `;` (could also use an explicit `return`).
(0..1000).fold(0, |old, new| old ^ new)
});
#}</code></pre></pre>
<p>Or, the other option is to call the generic <code>test::black_box</code> function, which
is an opaque "black box" to the optimizer and so forces it to consider any
argument as used.</p>
<pre><pre class="playpen"><code class="language-rust">#![feature(test)]
extern crate test;
# fn main() {
# struct X;
# impl X { fn iter<T, F>(&self, _: F) where F: FnMut() -> T {} } let b = X;
b.iter(|| {
let n = test::black_box(1000);
(0..n).fold(0, |a, b| a ^ b)
})
# }
</code></pre></pre>
<p>Neither of these read or modify the value, and are very cheap for small values.
Larger values can be passed indirectly to reduce overhead (e.g.
<code>black_box(&huge_struct)</code>).</p>
<p>Performing either of the above changes gives the following benchmarking results</p>
<pre><code class="language-text">running 1 test
test bench_xor_1000_ints ... bench: 131 ns/iter (+/- 3)
test result: ok. 0 passed; 0 failed; 0 ignored; 1 measured
</code></pre>
<p>However, the optimizer can still modify a testcase in an undesirable manner
even when using either of the above.</p>
<a class="header" href="print.html#thread_local_internals" id="thread_local_internals"><h1><code>thread_local_internals</code></h1></a>
<p>This feature is internal to the Rust compiler and is not intended for general use.</p>
<hr />
<a class="header" href="print.html#toowned_clone_into" id="toowned_clone_into"><h1><code>toowned_clone_into</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/41263">#41263</a></p>
<hr />
<a class="header" href="print.html#transpose_result" id="transpose_result"><h1><code>transpose_result</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/47338">#47338</a></p>
<hr />
<a class="header" href="print.html#trusted_len" id="trusted_len"><h1><code>trusted_len</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/37572">#37572</a></p>
<hr />
<a class="header" href="print.html#try_from" id="try_from"><h1><code>try_from</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/33417">#33417</a></p>
<hr />
<a class="header" href="print.html#try_reserve" id="try_reserve"><h1><code>try_reserve</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/48043">#48043</a></p>
<hr />
<a class="header" href="print.html#try_trait" id="try_trait"><h1><code>try_trait</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/42327">#42327</a></p>
<hr />
<p>This introduces a new trait <code>Try</code> for extending the <code>?</code> operator to types
other than <code>Result</code> (a part of <a href="https://github.com/rust-lang/rfcs/pull/1859">RFC 1859</a>). The trait provides the canonical
way to <em>view</em> a type in terms of a success/failure dichotomy. This will
allow <code>?</code> to supplant the <code>try_opt!</code> macro on <code>Option</code> and the <code>try_ready!</code>
macro on <code>Poll</code>, among other things.</p>
<p>Here's an example implementation of the trait:</p>
<pre><code class="language-rust ignore">/// A distinct type to represent the `None` value of an `Option`.
///
/// This enables using the `?` operator on `Option`; it's rarely useful alone.
#[derive(Debug)]
#[unstable(feature = "try_trait", issue = "42327")]
pub struct None { _priv: () }
#[unstable(feature = "try_trait", issue = "42327")]
impl<T> ops::Try for Option<T> {
type Ok = T;
type Error = None;
fn into_result(self) -> Result<T, None> {
self.ok_or(None { _priv: () })
}
fn from_ok(v: T) -> Self {
Some(v)
}
fn from_error(_: None) -> Self {
None
}
}
</code></pre>
<p>Note the <code>Error</code> associated type here is a new marker. The <code>?</code> operator
allows interconversion between different <code>Try</code> implementers only when
the error type can be converted <code>Into</code> the error type of the enclosing
function (or catch block). Having a distinct error type (as opposed to
just <code>()</code>, or similar) restricts this to where it's semantically meaningful.</p>
<a class="header" href="print.html#unicode" id="unicode"><h1><code>unicode</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/27783">#27783</a></p>
<hr />
<a class="header" href="print.html#unicode_internals" id="unicode_internals"><h1><code>unicode_internals</code></h1></a>
<p>This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.</p>
<hr />
<a class="header" href="print.html#unicode_version" id="unicode_version"><h1><code>unicode_version</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/49726">#49726</a></p>
<hr />
<a class="header" href="print.html#unsize" id="unsize"><h1><code>unsize</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/27732">#27732</a></p>
<hr />
<a class="header" href="print.html#update_panic_count" id="update_panic_count"><h1><code>update_panic_count</code></h1></a>
<p>This feature is internal to the Rust compiler and is not intended for general use.</p>
<hr />
<a class="header" href="print.html#vec_remove_item" id="vec_remove_item"><h1><code>vec_remove_item</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/40062">#40062</a></p>
<hr />
<a class="header" href="print.html#vec_resize_default" id="vec_resize_default"><h1><code>vec_resize_default</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/41758">#41758</a></p>
<hr />
<a class="header" href="print.html#vec_resize_with" id="vec_resize_with"><h1><code>vec_resize_with</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/41758">#41758</a></p>
<hr />
<a class="header" href="print.html#wait_timeout_until" id="wait_timeout_until"><h1><code>wait_timeout_until</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/47960">#47960</a></p>
<hr />
<a class="header" href="print.html#wait_until" id="wait_until"><h1><code>wait_until</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/47960">#47960</a></p>
<hr />
<a class="header" href="print.html#windows_c" id="windows_c"><h1><code>windows_c</code></h1></a>
<p>This feature is internal to the Rust compiler and is not intended for general use.</p>
<hr />
<a class="header" href="print.html#windows_file_type_ext" id="windows_file_type_ext"><h1><code>windows_file_type_ext</code></h1></a>
<p>This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.</p>
<hr />
<a class="header" href="print.html#windows_handle" id="windows_handle"><h1><code>windows_handle</code></h1></a>
<p>This feature is internal to the Rust compiler and is not intended for general use.</p>
<hr />
<a class="header" href="print.html#windows_net" id="windows_net"><h1><code>windows_net</code></h1></a>
<p>This feature is internal to the Rust compiler and is not intended for general use.</p>
<hr />
<a class="header" href="print.html#windows_stdio" id="windows_stdio"><h1><code>windows_stdio</code></h1></a>
<p>This feature is internal to the Rust compiler and is not intended for general use.</p>
<hr />
<a class="header" href="print.html#wrapping_int_impl" id="wrapping_int_impl"><h1><code>wrapping_int_impl</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/32463">#32463</a></p>
<hr />
<a class="header" href="print.html#wrapping_next_power_of_two" id="wrapping_next_power_of_two"><h1><code>wrapping_next_power_of_two</code></h1></a>
<p>The tracking issue for this feature is: <a href="https://github.com/rust-lang/rust/issues/32463">#32463</a></p>
<hr />
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<div style="clear: both"></div>
</nav>
</div>
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
</nav>
</div>
<script type="text/javascript">
document.addEventListener('DOMContentLoaded', function() {
window.print();
})
</script>
<script src="searchindex.js" type="text/javascript" charset="utf-8"></script>
<script src="elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
<script src="mark.min.js" type="text/javascript" charset="utf-8"></script>
<script src="searcher.js" type="text/javascript" charset="utf-8"></script>
<script src="clipboard.min.js" type="text/javascript" charset="utf-8"></script>
<script src="highlight.js" type="text/javascript" charset="utf-8"></script>
<script src="book.js" type="text/javascript" charset="utf-8"></script>
<!-- Custom JS scripts -->
</body>
</html>
distrib
>
Mageia
>
6
>
armv7hl
>
media
>
core-updates
>
by-pkgid
>
4e2dbb669434a7691662cb2f0ad38972
>
files
>
15600
