Literal in proc_macro - Rust
Description: A literal string (`"hello"`), byte string (`b"hello"`), C string (`c"hello"`), character (`'a'`), byte character (`b'a'`), an integer or floating point number with or without a suffix (`1`, `1u8`, `2.3`, `2.3f32`). Boolean literals like `true` and `false` do not belong here, they are `Ident`s.

## Literal

# Struct Literal

1.29.0 · Source

    pub struct Literal(/* private fields */);

Expand description

A literal string (`"hello"`), byte string (`b"hello"`), C string (`c"hello"`), character (`'a'`), byte character (`b'a'`), an integer or floating point number with or without a suffix (`1`, `1u8`, `2.3`, `2.3f32`). Boolean literals like `true` and `false` do not belong here, they are `Ident`s.

## Implementations§

Source§

### impl Literal

1.29.0 · Source

#### pub fn u8_suffixed(n: u8) -> Literal

Creates a new suffixed integer literal with the specified value.

This function will create an integer like `1u32` where the integer value specified is the first part of the token and the integral is also suffixed at the end. Literals created from negative numbers might not survive round-trips through `TokenStream` or strings and may be broken into two tokens (`-` and positive literal).

Literals created through this method have the `Span::call_site()` span by default, which can be configured with the `set_span` method below.

1.29.0 · Source

#### pub fn u16_suffixed(n: u16) -> Literal

Creates a new suffixed integer literal with the specified value.

This function will create an integer like `1u32` where the integer value specified is the first part of the token and the integral is also suffixed at the end. Literals created from negative numbers might not survive round-trips through `TokenStream` or strings and may be broken into two tokens (`-` and positive literal).

Literals created through this method have the `Span::call_site()` span by default, which can be configured with the `set_span` method below.

1.29.0 · Source

#### pub fn u32_suffixed(n: u32) -> Literal

Creates a new suffixed integer literal with the specified value.

This function will create an integer like `1u32` where the integer value specified is the first part of the token and the integral is also suffixed at the end. Literals created from negative numbers might not survive round-trips through `TokenStream` or strings and may be broken into two tokens (`-` and positive literal).

Literals created through this method have the `Span::call_site()` span by default, which can be configured with the `set_span` method below.

1.29.0 · Source

#### pub fn u64_suffixed(n: u64) -> Literal

Creates a new suffixed integer literal with the specified value.

This function will create an integer like `1u32` where the integer value specified is the first part of the token and the integral is also suffixed at the end. Literals created from negative numbers might not survive round-trips through `TokenStream` or strings and may be broken into two tokens (`-` and positive literal).

Literals created through this method have the `Span::call_site()` span by default, which can be configured with the `set_span` method below.

1.29.0 · Source

#### pub fn u128_suffixed(n: u128) -> Literal

Creates a new suffixed integer literal with the specified value.

This function will create an integer like `1u32` where the integer value specified is the first part of the token and the integral is also suffixed at the end. Literals created from negative numbers might not survive round-trips through `TokenStream` or strings and may be broken into two tokens (`-` and positive literal).

Literals created through this method have the `Span::call_site()` span by default, which can be configured with the `set_span` method below.

1.29.0 · Source

#### pub fn usize_suffixed(n: usize) -> Literal

Creates a new suffixed integer literal with the specified value.

This function will create an integer like `1u32` where the integer value specified is the first part of the token and the integral is also suffixed at the end. Literals created from negative numbers might not survive round-trips through `TokenStream` or strings and may be broken into two tokens (`-` and positive literal).

Literals created through this method have the `Span::call_site()` span by default, which can be configured with the `set_span` method below.

1.29.0 · Source

#### pub fn i8_suffixed(n: i8) -> Literal

Creates a new suffixed integer literal with the specified value.

This function will create an integer like `1u32` where the integer value specified is the first part of the token and the integral is also suffixed at the end. Literals created from negative numbers might not survive round-trips through `TokenStream` or strings and may be broken into two tokens (`-` and positive literal).

Literals created through this method have the `Span::call_site()` span by default, which can be configured with the `set_span` method below.

1.29.0 · Source

#### pub fn i16_suffixed(n: i16) -> Literal

Creates a new suffixed integer literal with the specified value.

This function will create an integer like `1u32` where the integer value specified is the first part of the token and the integral is also suffixed at the end. Literals created from negative numbers might not survive round-trips through `TokenStream` or strings and may be broken into two tokens (`-` and positive literal).

Literals created through this method have the `Span::call_site()` span by default, which can be configured with the `set_span` method below.

1.29.0 · Source

#### pub fn i32_suffixed(n: i32) -> Literal

Creates a new suffixed integer literal with the specified value.

This function will create an integer like `1u32` where the integer value specified is the first part of the token and the integral is also suffixed at the end. Literals created from negative numbers might not survive round-trips through `TokenStream` or strings and may be broken into two tokens (`-` and positive literal).

Literals created through this method have the `Span::call_site()` span by default, which can be configured with the `set_span` method below.

1.29.0 · Source

#### pub fn i64_suffixed(n: i64) -> Literal

Creates a new suffixed integer literal with the specified value.

This function will create an integer like `1u32` where the integer value specified is the first part of the token and the integral is also suffixed at the end. Literals created from negative numbers might not survive round-trips through `TokenStream` or strings and may be broken into two tokens (`-` and positive literal).

Literals created through this method have the `Span::call_site()` span by default, which can be configured with the `set_span` method below.

1.29.0 · Source

#### pub fn i128_suffixed(n: i128) -> Literal

Creates a new suffixed integer literal with the specified value.

This function will create an integer like `1u32` where the integer value specified is the first part of the token and the integral is also suffixed at the end. Literals created from negative numbers might not survive round-trips through `TokenStream` or strings and may be broken into two tokens (`-` and positive literal).

Literals created through this method have the `Span::call_site()` span by default, which can be configured with the `set_span` method below.

1.29.0 · Source

#### pub fn isize_suffixed(n: isize) -> Literal

Creates a new suffixed integer literal with the specified value.

This function will create an integer like `1u32` where the integer value specified is the first part of the token and the integral is also suffixed at the end. Literals created from negative numbers might not survive round-trips through `TokenStream` or strings and may be broken into two tokens (`-` and positive literal).

Literals created through this method have the `Span::call_site()` span by default, which can be configured with the `set_span` method below.

1.29.0 · Source

#### pub fn u8_unsuffixed(n: u8) -> Literal

Creates a new unsuffixed integer literal with the specified value.

This function will create an integer like `1` where the integer value specified is the first part of the token. No suffix is specified on this token, meaning that invocations like `Literal::i8_unsuffixed(1)` are equivalent to `Literal::u32_unsuffixed(1)`. Literals created from negative numbers might not survive rountrips through `TokenStream` or strings and may be broken into two tokens (`-` and positive literal).

Literals created through this method have the `Span::call_site()` span by default, which can be configured with the `set_span` method below.

1.29.0 · Source

#### pub fn u16_unsuffixed(n: u16) -> Literal

Creates a new unsuffixed integer literal with the specified value.

This function will create an integer like `1` where the integer value specified is the first part of the token. No suffix is specified on this token, meaning that invocations like `Literal::i8_unsuffixed(1)` are equivalent to `Literal::u32_unsuffixed(1)`. Literals created from negative numbers might not survive rountrips through `TokenStream` or strings and may be broken into two tokens (`-` and positive literal).

Literals created through this method have the `Span::call_site()` span by default, which can be configured with the `set_span` method below.

1.29.0 · Source

#### pub fn u32_unsuffixed(n: u32) -> Literal

Creates a new unsuffixed integer literal with the specified value.

This function will create an integer like `1` where the integer value specified is the first part of the token. No suffix is specified on this token, meaning that invocations like `Literal::i8_unsuffixed(1)` are equivalent to `Literal::u32_unsuffixed(1)`. Literals created from negative numbers might not survive rountrips through `TokenStream` or strings and may be broken into two tokens (`-` and positive literal).

Literals created through this method have the `Span::call_site()` span by default, which can be configured with the `set_span` method below.

1.29.0 · Source

#### pub fn u64_unsuffixed(n: u64) -> Literal

Creates a new unsuffixed integer literal with the specified value.

This function will create an integer like `1` where the integer value specified is the first part of the token. No suffix is specified on this token, meaning that invocations like `Literal::i8_unsuffixed(1)` are equivalent to `Literal::u32_unsuffixed(1)`. Literals created from negative numbers might not survive rountrips through `TokenStream` or strings and may be broken into two tokens (`-` and positive literal).

Literals created through this method have the `Span::call_site()` span by default, which can be configured with the `set_span` method below.

1.29.0 · Source

#### pub fn u128_unsuffixed(n: u128) -> Literal

Creates a new unsuffixed integer literal with the specified value.

This function will create an integer like `1` where the integer value specified is the first part of the token. No suffix is specified on this token, meaning that invocations like `Literal::i8_unsuffixed(1)` are equivalent to `Literal::u32_unsuffixed(1)`. Literals created from negative numbers might not survive rountrips through `TokenStream` or strings and may be broken into two tokens (`-` and positive literal).

Literals created through this method have the `Span::call_site()` span by default, which can be configured with the `set_span` method below.

1.29.0 · Source

#### pub fn usize_unsuffixed(n: usize) -> Literal

Creates a new unsuffixed integer literal with the specified value.

This function will create an integer like `1` where the integer value specified is the first part of the token. No suffix is specified on this token, meaning that invocations like `Literal::i8_unsuffixed(1)` are equivalent to `Literal::u32_unsuffixed(1)`. Literals created from negative numbers might not survive rountrips through `TokenStream` or strings and may be broken into two tokens (`-` and positive literal).

Literals created through this method have the `Span::call_site()` span by default, which can be configured with the `set_span` method below.

1.29.0 · Source

#### pub fn i8_unsuffixed(n: i8) -> Literal

Creates a new unsuffixed integer literal with the specified value.

This function will create an integer like `1` where the integer value specified is the first part of the token. No suffix is specified on this token, meaning that invocations like `Literal::i8_unsuffixed(1)` are equivalent to `Literal::u32_unsuffixed(1)`. Literals created from negative numbers might not survive rountrips through `TokenStream` or strings and may be broken into two tokens (`-` and positive literal).

Literals created through this method have the `Span::call_site()` span by default, which can be configured with the `set_span` method below.

1.29.0 · Source

#### pub fn i16_unsuffixed(n: i16) -> Literal

Creates a new unsuffixed integer literal with the specified value.

This function will create an integer like `1` where the integer value specified is the first part of the token. No suffix is specified on this token, meaning that invocations like `Literal::i8_unsuffixed(1)` are equivalent to `Literal::u32_unsuffixed(1)`. Literals created from negative numbers might not survive rountrips through `TokenStream` or strings and may be broken into two tokens (`-` and positive literal).

Literals created through this method have the `Span::call_site()` span by default, which can be configured with the `set_span` method below.

1.29.0 · Source

#### pub fn i32_unsuffixed(n: i32) -> Literal

Creates a new unsuffixed integer literal with the specified value.

This function will create an integer like `1` where the integer value specified is the first part of the token. No suffix is specified on this token, meaning that invocations like `Literal::i8_unsuffixed(1)` are equivalent to `Literal::u32_unsuffixed(1)`. Literals created from negative numbers might not survive rountrips through `TokenStream` or strings and may be broken into two tokens (`-` and positive literal).

Literals created through this method have the `Span::call_site()` span by default, which can be configured with the `set_span` method below.

1.29.0 · Source

#### pub fn i64_unsuffixed(n: i64) -> Literal

Creates a new unsuffixed integer literal with the specified value.

This function will create an integer like `1` where the integer value specified is the first part of the token. No suffix is specified on this token, meaning that invocations like `Literal::i8_unsuffixed(1)` are equivalent to `Literal::u32_unsuffixed(1)`. Literals created from negative numbers might not survive rountrips through `TokenStream` or strings and may be broken into two tokens (`-` and positive literal).

Literals created through this method have the `Span::call_site()` span by default, which can be configured with the `set_span` method below.

1.29.0 · Source

#### pub fn i128_unsuffixed(n: i128) -> Literal

Creates a new unsuffixed integer literal with the specified value.

This function will create an integer like `1` where the integer value specified is the first part of the token. No suffix is specified on this token, meaning that invocations like `Literal::i8_unsuffixed(1)` are equivalent to `Literal::u32_unsuffixed(1)`. Literals created from negative numbers might not survive rountrips through `TokenStream` or strings and may be broken into two tokens (`-` and positive literal).

Literals created through this method have the `Span::call_site()` span by default, which can be configured with the `set_span` method below.

1.29.0 · Source

#### pub fn isize_unsuffixed(n: isize) -> Literal

Creates a new unsuffixed integer literal with the specified value.

This function will create an integer like `1` where the integer value specified is the first part of the token. No suffix is specified on this token, meaning that invocations like `Literal::i8_unsuffixed(1)` are equivalent to `Literal::u32_unsuffixed(1)`. Literals created from negative numbers might not survive rountrips through `TokenStream` or strings and may be broken into two tokens (`-` and positive literal).

Literals created through this method have the `Span::call_site()` span by default, which can be configured with the `set_span` method below.

1.29.0 · Source

#### pub fn f32_unsuffixed(n: f32) -> Literal

Creates a new unsuffixed floating-point literal.

This constructor is similar to those like `Literal::i8_unsuffixed` where the float’s value is emitted directly into the token but no suffix is used, so it may be inferred to be a `f64` later in the compiler. Literals created from negative numbers might not survive rountrips through `TokenStream` or strings and may be broken into two tokens (`-` and positive literal).

##### §Panics

This function requires that the specified float is finite, for example if it is infinity or NaN this function will panic.

1.29.0 · Source

#### pub fn f32_suffixed(n: f32) -> Literal

Creates a new suffixed floating-point literal.

This constructor will create a literal like `1.0f32` where the value specified is the preceding part of the token and `f32` is the suffix of the token. This token will always be inferred to be an `f32` in the compiler. Literals created from negative numbers might not survive rountrips through `TokenStream` or strings and may be broken into two tokens (`-` and positive literal).

##### §Panics

This function requires that the specified float is finite, for example if it is infinity or NaN this function will panic.

1.29.0 · Source

#### pub fn f64_unsuffixed(n: f64) -> Literal

Creates a new unsuffixed floating-point literal.

This constructor is similar to those like `Literal::i8_unsuffixed` where the float’s value is emitted directly into the token but no suffix is used, so it may be inferred to be a `f64` later in the compiler. Literals created from negative numbers might not survive rountrips through `TokenStream` or strings and may be broken into two tokens (`-` and positive literal).

##### §Panics

This function requires that the specified float is finite, for example if it is infinity or NaN this function will panic.

1.29.0 · Source

#### pub fn f64_suffixed(n: f64) -> Literal

Creates a new suffixed floating-point literal.

This constructor will create a literal like `1.0f64` where the value specified is the preceding part of the token and `f64` is the suffix of the token. This token will always be inferred to be an `f64` in the compiler. Literals created from negative numbers might not survive rountrips through `TokenStream` or strings and may be broken into two tokens (`-` and positive literal).

##### §Panics

This function requires that the specified float is finite, for example if it is infinity or NaN this function will panic.

1.29.0 · Source

#### pub fn string(string: &str) -> Literal

String literal.

1.29.0 · Source

#### pub fn character(ch: char) -> Literal

Character literal.

1.79.0 · Source

#### pub fn byte_character(byte: u8) -> Literal

Byte character literal.

1.29.0 · Source

#### pub fn byte_string(bytes: &[u8]) -> Literal

Byte string literal.

1.79.0 · Source

#### pub fn c_string(string: &CStr) -> Literal

C string literal.

1.29.0 · Source

#### pub fn span(&self) -> Span

Returns the span encompassing this literal.

1.29.0 · Source

#### pub fn set_span(&mut self, span: Span)

Configures the span associated for this literal.

Source

#### pub fn subspan<R: RangeBounds<usize>>(&self, range: R) -> Option<Span>

🔬This is a nightly-only experimental API. (`proc_macro_span` #54725)

Returns a `Span` that is a subset of `self.span()` containing only the source bytes in range `range`. Returns `None` if the would-be trimmed span is outside the bounds of `self`.

Source

#### pub fn str_value(&self) -> Result<String, ConversionErrorKind>

🔬This is a nightly-only experimental API. (`proc_macro_value` #136652)

Returns the unescaped string value if the current literal is a string or a string literal.

Source

#### pub fn cstr_value(&self) -> Result<Vec<u8>, ConversionErrorKind>

🔬This is a nightly-only experimental API. (`proc_macro_value` #136652)

Returns the unescaped string value if the current literal is a c-string or a c-string literal.

Source

#### pub fn byte_str_value(&self) -> Result<Vec<u8>, ConversionErrorKind>

🔬This is a nightly-only experimental API. (`proc_macro_value` #136652)

Returns the unescaped string value if the current literal is a byte string or a byte string literal.

## Trait Implementations§

1.29.0 · Source§

### impl Clone for Literal

Source§

#### fn clone(&self) -> Literal

Returns a duplicate of the value. Read more
1.0.0 · Source§

#### fn clone_from(&mut self, source: &Self)

Performs copy-assignment from `source`. Read more
1.29.0 · Source§

### impl Debug for Literal

Source§

#### fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
1.29.0 · Source§

### impl Display for Literal

Prints the literal as a string that should be losslessly convertible back into the same literal (except for possible rounding for floating point literals).

Source§

#### fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
1.92.0 · Source§

### impl Extend<Literal> for TokenStream

Source§

#### fn extend<T: IntoIterator<Item = Literal>>(&mut self, iter: T)

Extends a collection with the contents of an iterator. Read more
Source§

#### fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (`extend_one` #72631)
Extends a collection with exactly one element.
Source§

#### fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (`extend_one` #72631)
Reserves capacity in a collection for the given number of additional elements. Read more
1.29.0 · Source§

### impl From<Literal> for TokenTree

Source§

#### fn from(g: Literal) -> TokenTree

Converts to this type from the input type.
1.54.0 · Source§

### impl FromStr for Literal

Parse a single literal from its stringified representation.

In order to parse successfully, the input string must not contain anything but the literal token. Specifically, it must not contain whitespace or comments in addition to the literal.

The resulting literal token will have a `Span::call_site()` span.

NOTE: some errors may cause panics instead of returning `LexError`. We reserve the right to change these errors into `LexError`s later.

Source§

#### type Err = LexError

The associated error which can be returned from parsing.
Source§

#### fn from_str(src: &str) -> Result<Self, LexError>

Parses a string `s` to return a value of this type. Read more
Source§

### impl ToTokens for Literal

Source§

#### fn to_tokens(&self, tokens: &mut TokenStream)

🔬This is a nightly-only experimental API. (`proc_macro_totokens` #130977)
Write `self` to the given `TokenStream`. Read more
Source§

#### fn to_token_stream(&self) -> TokenStream

🔬This is a nightly-only experimental API. (`proc_macro_totokens` #130977)
Convert `self` directly into a `TokenStream` object. Read more
Source§

#### fn into_token_stream(self) -> TokenStream
where Self: Sized,

🔬This is a nightly-only experimental API. (`proc_macro_totokens` #130977)
Convert `self` directly into a `TokenStream` object. Read more

## Auto Trait Implementations§

§

### impl Freeze for Literal

§

### impl RefUnwindSafe for Literal

§

### impl !Send for Literal

§

### impl !Sync for Literal

§

### impl Unpin for Literal

§

### impl UnwindSafe for Literal

## Blanket Implementations§

Source§

### impl<T> Any for T
where T: 'static + ?Sized,

Source§

#### fn type_id(&self) -> TypeId

Gets the `TypeId` of `self`. Read more
Source§

### impl<T> Borrow<T> for T
where T: ?Sized,

Source§

#### fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

### impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

#### fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

### impl<T> CloneToUninit for T
where T: Clone,

Source§

#### unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (`clone_to_uninit` #126799)
Performs copy-assignment from `self` to `dest`. Read more
Source§

### impl<T> From<T> for T

Source§

#### fn from(t: T) -> T

Returns the argument unchanged.

Source§

### impl<T, U> Into<U> for T
where U: From<T>,

Source§

#### fn into(self) -> U

Calls `U::from(self)`.

That is, this conversion is whatever the implementation of `From<T> for U` chooses to do.

Source§

### impl<T> ToOwned for T
where T: Clone,

Source§

#### type Owned = T

The resulting type after obtaining ownership.
Source§

#### fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

#### fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

### impl<T> ToString for T
where T: Display + ?Sized,

Source§

#### fn to_string(&self) -> String

Converts the given value to a `String`. Read more
Source§

### impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

#### type Error = Infallible

The type returned in the event of a conversion error.
Source§

#### fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

### impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

#### type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

#### fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.