-use crate::reexport::*;
+pub mod attrs;
+pub mod author;
+pub mod camel_case;
+pub mod comparisons;
+pub mod conf;
+pub mod constants;
+mod diagnostics;
+pub mod higher;
+mod hir_utils;
+pub mod inspector;
+pub mod internal_lints;
+pub mod paths;
+pub mod ptr;
+pub mod sugg;
+pub mod usage;
+pub use self::attrs::*;
+pub use self::diagnostics::*;
+pub use self::hir_utils::{SpanlessEq, SpanlessHash};
+
+use std::borrow::Cow;
+use std::mem;
+
use if_chain::if_chain;
use matches::matches;
use rustc::hir;
use rustc::hir::def::Def;
+use rustc::hir::map::DisambiguatedDefPathData;
+use rustc::hir::def_id::CrateNum;
use rustc::hir::def_id::{DefId, CRATE_DEF_INDEX, LOCAL_CRATE};
use rustc::hir::intravisit::{NestedVisitorMap, Visitor};
use rustc::hir::Node;
use rustc::hir::*;
use rustc::lint::{LateContext, Level, Lint, LintContext};
-use rustc::session::Session;
use rustc::traits;
use rustc::ty::{
self,
};
use rustc_data_structures::sync::Lrc;
use rustc_errors::Applicability;
-use std::borrow::Cow;
-use std::mem;
-use std::str::FromStr;
use syntax::ast::{self, LitKind};
use syntax::attr;
use syntax::source_map::{Span, DUMMY_SP};
-use syntax::symbol;
use syntax::symbol::{keywords, Symbol};
-pub mod camel_case;
-
-pub mod author;
-pub mod comparisons;
-pub mod conf;
-pub mod constants;
-mod diagnostics;
-mod hir_utils;
-pub mod inspector;
-pub mod internal_lints;
-pub mod paths;
-pub mod ptr;
-pub mod sugg;
-pub mod usage;
-pub use self::diagnostics::*;
-pub use self::hir_utils::{SpanlessEq, SpanlessHash};
-
-pub mod higher;
+use crate::reexport::*;
-/// Returns true if the two spans come from differing expansions (i.e. one is
-/// from a macro and one
-/// isn't).
+/// Returns `true` if the two spans come from differing expansions (i.e., one is
+/// from a macro and one isn't).
pub fn differing_macro_contexts(lhs: Span, rhs: Span) -> bool {
rhs.ctxt() != lhs.ctxt()
}
}
}
-/// Returns true if this `expn_info` was expanded by any macro.
+/// Returns `true` if this `expn_info` was expanded by any macro.
pub fn in_macro(span: Span) -> bool {
span.ctxt().outer().expn_info().is_some()
}
/// Used to store the absolute path to a type.
///
/// See `match_def_path` for usage.
-#[derive(Debug)]
-pub struct AbsolutePathBuffer {
- pub names: Vec<symbol::LocalInternedString>,
+pub struct AbsolutePathPrinter<'a, 'tcx> {
+ pub tcx: TyCtxt<'a, 'tcx, 'tcx>,
}
-impl ty::item_path::ItemPathBuffer for AbsolutePathBuffer {
- fn root_mode(&self) -> &ty::item_path::RootMode {
- const ABSOLUTE: &ty::item_path::RootMode = &ty::item_path::RootMode::Absolute;
- ABSOLUTE
+use rustc::ty::print::Printer;
+
+impl<'tcx> Printer<'tcx, 'tcx> for AbsolutePathPrinter<'_, 'tcx> {
+ type Error = !;
+
+ type Path = Vec<String>;
+ type Region = ();
+ type Type = ();
+ type DynExistential = ();
+
+ fn tcx<'a>(&'a self) -> TyCtxt<'a, 'tcx, 'tcx> {
+ self.tcx
+ }
+
+ fn print_region(
+ self,
+ _region: ty::Region<'_>,
+ ) -> Result<Self::Region, Self::Error> {
+ Ok(())
+ }
+
+ fn print_type(
+ self,
+ _ty: Ty<'tcx>,
+ ) -> Result<Self::Type, Self::Error> {
+ Ok(())
+ }
+
+ fn print_dyn_existential(
+ self,
+ _predicates: &'tcx ty::List<ty::ExistentialPredicate<'tcx>>,
+ ) -> Result<Self::DynExistential, Self::Error> {
+ Ok(())
+ }
+
+ fn path_crate(
+ self,
+ cnum: CrateNum,
+ ) -> Result<Self::Path, Self::Error> {
+ Ok(vec![self.tcx.original_crate_name(cnum).to_string()])
+ }
+ fn path_qualified(
+ self,
+ self_ty: Ty<'tcx>,
+ trait_ref: Option<ty::TraitRef<'tcx>>,
+ ) -> Result<Self::Path, Self::Error> {
+ // This shouldn't ever be needed, but just in case:
+ Ok(vec![match trait_ref {
+ Some(trait_ref) => format!("{:?}", trait_ref),
+ None => format!("<{}>", self_ty),
+ }])
}
- fn push(&mut self, text: &str) {
- self.names.push(symbol::Symbol::intern(text).as_str());
+ fn path_append_impl(
+ self,
+ print_prefix: impl FnOnce(Self) -> Result<Self::Path, Self::Error>,
+ _disambiguated_data: &DisambiguatedDefPathData,
+ self_ty: Ty<'tcx>,
+ trait_ref: Option<ty::TraitRef<'tcx>>,
+ ) -> Result<Self::Path, Self::Error> {
+ let mut path = print_prefix(self)?;
+
+ // This shouldn't ever be needed, but just in case:
+ path.push(match trait_ref {
+ Some(trait_ref) => {
+ format!("<impl {} for {}>", trait_ref, self_ty)
+ }
+ None => format!("<impl {}>", self_ty),
+ });
+
+ Ok(path)
+ }
+ fn path_append(
+ self,
+ print_prefix: impl FnOnce(Self) -> Result<Self::Path, Self::Error>,
+ disambiguated_data: &DisambiguatedDefPathData,
+ ) -> Result<Self::Path, Self::Error> {
+ let mut path = print_prefix(self)?;
+ path.push(disambiguated_data.data.as_interned_str().to_string());
+ Ok(path)
+ }
+ fn path_generic_args(
+ self,
+ print_prefix: impl FnOnce(Self) -> Result<Self::Path, Self::Error>,
+ _args: &[Kind<'tcx>],
+ ) -> Result<Self::Path, Self::Error> {
+ print_prefix(self)
}
}
-/// Check if a `DefId`'s path matches the given absolute type path usage.
+/// Checks if a `DefId`'s path matches the given absolute type path usage.
///
/// # Examples
/// ```rust,ignore
/// ```
///
/// See also the `paths` module.
-pub fn match_def_path(tcx: TyCtxt<'_, '_, '_>, def_id: DefId, path: &[&str]) -> bool {
- let mut apb = AbsolutePathBuffer { names: vec![] };
-
- tcx.push_item_path(&mut apb, def_id, false);
+pub fn match_def_path<'a, 'tcx>(tcx: TyCtxt<'a, 'tcx, 'tcx>, def_id: DefId, path: &[&str]) -> bool {
+ let names = AbsolutePathPrinter { tcx }.print_def_path(def_id, &[]).unwrap();
- apb.names.len() == path.len() && apb.names.into_iter().zip(path.iter()).all(|(a, &b)| *a == *b)
+ names.len() == path.len() && names.into_iter().zip(path.iter()).all(|(a, &b)| *a == *b)
}
-/// Get the absolute path of `def_id` as a vector of `&str`.
+/// Gets the absolute path of `def_id` as a vector of `&str`.
///
/// # Examples
/// ```rust,ignore
/// // The given `def_id` is that of an `Option` type
/// };
/// ```
-pub fn get_def_path(tcx: TyCtxt<'_, '_, '_>, def_id: DefId) -> Vec<&'static str> {
- let mut apb = AbsolutePathBuffer { names: vec![] };
- tcx.push_item_path(&mut apb, def_id, false);
- apb.names
- .iter()
- .map(syntax_pos::symbol::LocalInternedString::get)
- .collect()
+pub fn get_def_path<'a, 'tcx>(tcx: TyCtxt<'a, 'tcx, 'tcx>, def_id: DefId) -> Vec<String> {
+ AbsolutePathPrinter { tcx }.print_def_path(def_id, &[]).unwrap()
}
-/// Check if type is struct, enum or union type with given def path.
+/// Checks if type is struct, enum or union type with the given def path.
pub fn match_type(cx: &LateContext<'_, '_>, ty: Ty<'_>, path: &[&str]) -> bool {
match ty.sty {
ty::Adt(adt, _) => match_def_path(cx.tcx, adt.did, path),
}
}
-/// Check if the method call given in `expr` belongs to given trait.
+/// Checks if the method call given in `expr` belongs to the given trait.
pub fn match_trait_method(cx: &LateContext<'_, '_>, expr: &Expr, path: &[&str]) -> bool {
let method_call = cx.tables.type_dependent_defs()[expr.hir_id];
let trt_id = cx.tcx.trait_of_item(method_call.def_id());
}
}
-/// Check if an expression references a variable of the given name.
+/// Checks if an expression references a variable of the given name.
pub fn match_var(expr: &Expr, var: Name) -> bool {
if let ExprKind::Path(QPath::Resolved(None, ref path)) = expr.node {
if path.segments.len() == 1 && path.segments[0].ident.name == var {
}
}
-/// Match a `Path` against a slice of segment string literals.
+/// Matches a `QPath` against a slice of segment string literals.
+///
+/// There is also `match_path` if you are dealing with a `rustc::hir::Path` instead of a
+/// `rustc::hir::QPath`.
///
/// # Examples
/// ```rust,ignore
}
}
+/// Matches a `Path` against a slice of segment string literals.
+///
+/// There is also `match_qpath` if you are dealing with a `rustc::hir::QPath` instead of a
+/// `rustc::hir::Path`.
+///
+/// # Examples
+///
+/// ```rust,ignore
+/// if match_path(&trait_ref.path, &paths::HASH) {
+/// // This is the `std::hash::Hash` trait.
+/// }
+///
+/// if match_path(ty_path, &["rustc", "lint", "Lint"]) {
+/// // This is a `rustc::lint::Lint`.
+/// }
+/// ```
pub fn match_path(path: &Path, segments: &[&str]) -> bool {
path.segments
.iter()
.all(|(a, b)| a.ident.name == *b)
}
-/// Match a `Path` against a slice of segment string literals, e.g.
+/// Matches a `Path` against a slice of segment string literals, e.g.
///
/// # Examples
/// ```rust,ignore
.all(|(a, b)| a.ident.name == *b)
}
-/// Get the definition associated to a path.
+/// Gets the definition associated to a path.
pub fn path_to_def(cx: &LateContext<'_, '_>, path: &[&str]) -> Option<def::Def> {
let crates = cx.tcx.crates();
let krate = crates.iter().find(|&&krate| cx.tcx.crate_name(krate) == path[0]);
}
}
-/// Check whether a type implements a trait.
+/// Checks whether a type implements a trait.
/// See also `get_trait_def_id`.
pub fn implements_trait<'a, 'tcx>(
cx: &LateContext<'a, 'tcx>,
.enter(|infcx| infcx.predicate_must_hold_modulo_regions(&obligation))
}
-/// Check whether this type implements Drop.
+/// Gets the `hir::TraitRef` of the trait the given method is implemented for.
+///
+/// Use this if you want to find the `TraitRef` of the `Add` trait in this example:
+///
+/// ```rust
+/// struct Point(isize, isize);
+///
+/// impl std::ops::Add for Point {
+/// type Output = Self;
+///
+/// fn add(self, other: Self) -> Self {
+/// Point(0, 0)
+/// }
+/// }
+/// ```
+pub fn trait_ref_of_method(cx: &LateContext<'_, '_>, hir_id: HirId) -> Option<TraitRef> {
+ // Get the implemented trait for the current function
+ let parent_impl = cx.tcx.hir().get_parent_item(hir_id);
+ if_chain! {
+ if parent_impl != hir::CRATE_HIR_ID;
+ if let hir::Node::Item(item) = cx.tcx.hir().get_by_hir_id(parent_impl);
+ if let hir::ItemKind::Impl(_, _, _, _, trait_ref, _, _) = &item.node;
+ then { return trait_ref.clone(); }
+ }
+ None
+}
+
+/// Checks whether this type implements `Drop`.
pub fn has_drop<'a, 'tcx>(cx: &LateContext<'a, 'tcx>, ty: Ty<'tcx>) -> bool {
match ty.ty_adt_def() {
Some(def) => def.has_dtor(cx.tcx),
}
}
-/// Resolve the definition of a node from its `HirId`.
+/// Resolves the definition of a node from its `HirId`.
pub fn resolve_node(cx: &LateContext<'_, '_>, qpath: &QPath, id: HirId) -> def::Def {
cx.tables.qpath_def(qpath, id)
}
-/// Return the method names and argument list of nested method call expressions that make up
+/// Returns the method names and argument list of nested method call expressions that make up
/// `expr`.
pub fn method_calls<'a>(expr: &'a Expr, max_depth: usize) -> (Vec<Symbol>, Vec<&'a [Expr]>) {
let mut method_names = Vec::with_capacity(max_depth);
(method_names, arg_lists)
}
-/// Match an `Expr` against a chain of methods, and return the matched `Expr`s.
+/// Matches an `Expr` against a chain of methods, and return the matched `Expr`s.
///
/// For example, if `expr` represents the `.baz()` in `foo.bar().baz()`,
/// `matched_method_chain(expr, &["bar", "baz"])` will return a `Vec`
return None;
}
}
- matched.reverse(); // reverse `matched`, so that it is in the same order as `methods`
+ // Reverse `matched` so that it is in the same order as `methods`.
+ matched.reverse();
Some(matched)
}
-/// Returns true if the provided `def_id` is an entrypoint to a program
+/// Returns `true` if the provided `def_id` is an entrypoint to a program.
pub fn is_entrypoint_fn(cx: &LateContext<'_, '_>, def_id: DefId) -> bool {
if let Some((entry_fn_def_id, _)) = cx.tcx.entry_fn(LOCAL_CRATE) {
return def_id == entry_fn_def_id;
false
}
-/// Get the name of the item the expression is in, if available.
+/// Gets the name of the item the expression is in, if available.
pub fn get_item_name(cx: &LateContext<'_, '_>, expr: &Expr) -> Option<Name> {
let parent_id = cx.tcx.hir().get_parent_item(expr.hir_id);
match cx.tcx.hir().find_by_hir_id(parent_id) {
}
}
-/// Get the name of a `Pat`, if any
+/// Gets the name of a `Pat`, if any.
pub fn get_pat_name(pat: &Pat) -> Option<Name> {
match pat.node {
PatKind::Binding(.., ref spname, _) => Some(spname.name),
}
}
-/// check if an `Expr` contains a certain name
+/// Checks if an `Expr` contains a certain name.
pub fn contains_name(name: Name, expr: &Expr) -> bool {
let mut cn = ContainsName { name, result: false };
cn.visit_expr(expr);
cn.result
}
-/// Convert a span to a code snippet if available, otherwise use default.
+/// Converts a span to a code snippet if available, otherwise use default.
///
/// This is useful if you want to provide suggestions for your lint or more generally, if you want
/// to convert a given `Span` to a `str`.
snippet(cx, span.source_callsite(), default)
}
-/// Convert a span to a code snippet. Returns `None` if not available.
+/// Converts a span to a code snippet. Returns `None` if not available.
pub fn snippet_opt<'a, T: LintContext<'a>>(cx: &T, span: Span) -> Option<String> {
cx.sess().source_map().span_to_snippet(span).ok()
}
-/// Convert a span (from a block) to a code snippet if available, otherwise use
+/// Converts a span (from a block) to a code snippet if available, otherwise use
/// default.
/// This trims the code of indentation, except for the first line. Use it for
/// blocks or block-like
}
}
-/// Get a parent expressions if any – this is useful to constrain a lint.
+/// Gets the parent expression, if any –- this is useful to constrain a lint.
pub fn get_parent_expr<'c>(cx: &'c LateContext<'_, '_>, e: &Expr) -> Option<&'c Expr> {
let map = &cx.tcx.hir();
let hir_id = e.hir_id;
}
}
-/// Return the base type for HIR references and pointers.
+/// Returns the base type for HIR references and pointers.
pub fn walk_ptrs_hir_ty(ty: &hir::Ty) -> &hir::Ty {
match ty.node {
TyKind::Ptr(ref mut_ty) | TyKind::Rptr(_, ref mut_ty) => walk_ptrs_hir_ty(&mut_ty.ty),
}
}
-/// Return the base type for references and raw pointers.
+/// Returns the base type for references and raw pointers.
pub fn walk_ptrs_ty(ty: Ty<'_>) -> Ty<'_> {
match ty.sty {
ty::Ref(_, ty, _) => walk_ptrs_ty(ty),
}
}
-/// Return the base type for references and raw pointers, and count reference
+/// Returns the base type for references and raw pointers, and count reference
/// depth.
pub fn walk_ptrs_ty_depth(ty: Ty<'_>) -> (Ty<'_>, usize) {
fn inner(ty: Ty<'_>, depth: usize) -> (Ty<'_>, usize) {
inner(ty, 0)
}
-/// Check whether the given expression is a constant literal of the given value.
+/// Checks whether the given expression is a constant literal of the given value.
pub fn is_integer_literal(expr: &Expr, value: u128) -> bool {
// FIXME: use constant folding
if let ExprKind::Lit(ref spanned) = expr.node {
cx.tables.adjustments().get(e.hir_id).is_some()
}
-pub struct LimitStack {
- stack: Vec<u64>,
-}
-
-impl Drop for LimitStack {
- fn drop(&mut self) {
- assert_eq!(self.stack.len(), 1);
- }
-}
-
-impl LimitStack {
- pub fn new(limit: u64) -> Self {
- Self { stack: vec![limit] }
- }
- pub fn limit(&self) -> u64 {
- *self.stack.last().expect("there should always be a value in the stack")
- }
- pub fn push_attrs(&mut self, sess: &Session, attrs: &[ast::Attribute], name: &'static str) {
- let stack = &mut self.stack;
- parse_attrs(sess, attrs, name, |val| stack.push(val));
- }
- pub fn pop_attrs(&mut self, sess: &Session, attrs: &[ast::Attribute], name: &'static str) {
- let stack = &mut self.stack;
- parse_attrs(sess, attrs, name, |val| assert_eq!(stack.pop(), Some(val)));
- }
-}
-
-pub fn get_attr<'a>(attrs: &'a [ast::Attribute], name: &'static str) -> impl Iterator<Item = &'a ast::Attribute> {
- attrs.iter().filter(move |attr| {
- attr.path.segments.len() == 2
- && attr.path.segments[0].ident.to_string() == "clippy"
- && attr.path.segments[1].ident.to_string() == name
- })
-}
-
-fn parse_attrs<F: FnMut(u64)>(sess: &Session, attrs: &[ast::Attribute], name: &'static str, mut f: F) {
- for attr in get_attr(attrs, name) {
- if let Some(ref value) = attr.value_str() {
- if let Ok(value) = FromStr::from_str(&value.as_str()) {
- f(value)
- } else {
- sess.span_err(attr.span, "not a number");
- }
- } else {
- sess.span_err(attr.span, "bad clippy attribute");
- }
- }
-}
-
-/// Return the pre-expansion span if is this comes from an expansion of the
+/// Returns the pre-expansion span if is this comes from an expansion of the
/// macro `name`.
/// See also `is_direct_expn_of`.
pub fn is_expn_of(mut span: Span, name: &str) -> Option<Span> {
}
}
-/// Return the pre-expansion span if is this directly comes from an expansion
+/// Returns the pre-expansion span if the span directly comes from an expansion
/// of the macro `name`.
/// The difference with `is_expn_of` is that in
/// ```rust,ignore
}
}
-/// Convenience function to get the return type of a function
-pub fn return_ty<'a, 'tcx>(cx: &LateContext<'a, 'tcx>, fn_item: NodeId) -> Ty<'tcx> {
- let fn_def_id = cx.tcx.hir().local_def_id(fn_item);
+/// Convenience function to get the return type of a function.
+pub fn return_ty<'a, 'tcx>(cx: &LateContext<'a, 'tcx>, fn_item: hir::HirId) -> Ty<'tcx> {
+ let fn_def_id = cx.tcx.hir().local_def_id_from_hir_id(fn_item);
let ret_ty = cx.tcx.fn_sig(fn_def_id).output();
cx.tcx.erase_late_bound_regions(&ret_ty)
}
-/// Check if two types are the same.
+/// Checks if two types are the same.
///
/// This discards any lifetime annotations, too.
-// FIXME: this works correctly for lifetimes bounds (`for <'a> Foo<'a>` == `for
-// <'b> Foo<'b>` but
-// not for type parameters.
+//
+// FIXME: this works correctly for lifetimes bounds (`for <'a> Foo<'a>` ==
+// `for <'b> Foo<'b>`, but not for type parameters).
pub fn same_tys<'a, 'tcx>(cx: &LateContext<'a, 'tcx>, a: Ty<'tcx>, b: Ty<'tcx>) -> bool {
let a = cx.tcx.erase_late_bound_regions(&Binder::bind(a));
let b = cx.tcx.erase_late_bound_regions(&Binder::bind(b));
.enter(|infcx| infcx.can_eq(cx.param_env, a, b).is_ok())
}
-/// Return whether the given type is an `unsafe` function.
+/// Returns `true` if the given type is an `unsafe` function.
pub fn type_is_unsafe_function<'a, 'tcx>(cx: &LateContext<'a, 'tcx>, ty: Ty<'tcx>) -> bool {
match ty.sty {
ty::FnDef(..) | ty::FnPtr(_) => ty.fn_sig(cx.tcx).unsafety() == Unsafety::Unsafe,
ty.is_copy_modulo_regions(cx.tcx.global_tcx(), cx.param_env, DUMMY_SP)
}
-/// Return whether a pattern is refutable.
+/// Returns `true` if a pattern is refutable.
pub fn is_refutable(cx: &LateContext<'_, '_>, pat: &Pat) -> bool {
fn is_enum_variant(cx: &LateContext<'_, '_>, qpath: &QPath, id: HirId) -> bool {
matches!(
}
}
-pub fn opt_def_id(def: Def) -> Option<DefId> {
- def.opt_def_id()
-}
-
pub fn is_self(slf: &Arg) -> bool {
if let PatKind::Binding(.., name, _) = slf.pat.node {
name.name == keywords::SelfLower.name()
(0..decl.inputs.len()).map(move |i| &body.arguments[i])
}
-/// Check if a given expression is a match expression
-/// expanded from `?` operator or `try` macro.
-pub fn is_try(expr: &Expr) -> Option<&Expr> {
- fn is_ok(arm: &Arm) -> bool {
+/// Checks if a given expression is a match expression expanded from the `?`
+/// operator or the `try` macro.
+pub fn is_try<'a>(cx: &'_ LateContext<'_, '_>, expr: &'a Expr) -> Option<&'a Expr> {
+ fn is_ok(cx: &'_ LateContext<'_, '_>, arm: &Arm) -> bool {
if_chain! {
if let PatKind::TupleStruct(ref path, ref pat, None) = arm.pats[0].node;
if match_qpath(path, &paths::RESULT_OK[1..]);
- if let PatKind::Binding(_, defid, _, _, None) = pat[0].node;
+ if let PatKind::Binding(_, hir_id, _, None) = pat[0].node;
if let ExprKind::Path(QPath::Resolved(None, ref path)) = arm.body.node;
if let Def::Local(lid) = path.def;
- if lid == defid;
+ if cx.tcx.hir().node_to_hir_id(lid) == hir_id;
then {
return true;
}
if arms.len() == 2;
if arms[0].pats.len() == 1 && arms[0].guard.is_none();
if arms[1].pats.len() == 1 && arms[1].guard.is_none();
- if (is_ok(&arms[0]) && is_err(&arms[1])) ||
- (is_ok(&arms[1]) && is_err(&arms[0]));
+ if (is_ok(cx, &arms[0]) && is_err(&arms[1])) ||
+ (is_ok(cx, &arms[1]) && is_err(&arms[0]));
then {
return Some(expr);
}
None
}
-/// Returns true if the lint is allowed in the current context
+/// Returns `true` if the lint is allowed in the current context
///
/// Useful for skipping long running code when it's unnecessary
pub fn is_allowed(cx: &LateContext<'_, '_>, lint: &'static Lint, id: HirId) -> bool {
- let node_id = cx.tcx.hir().hir_to_node_id(id);
- cx.tcx.lint_level_at_node(lint, node_id).0 == Level::Allow
+ cx.tcx.lint_level_at_node(lint, id).0 == Level::Allow
}
pub fn get_arg_name(pat: &Pat) -> Option<ast::Name> {
(u << amt) >> amt
}
-/// Remove block comments from the given Vec of lines
+/// Removes block comments from the given `Vec` of lines.
///
/// # Examples
///