[−][src]Macro lark_collections::index_type

macro_rules! index_type {
    ($(#[$attr:meta])* $visibility:vis struct $name:ident { $($tokens:tt)* }) => { ... };
    (
        @with {
            attrs[$($attrs:meta)*],
            visibility[$visibility:vis],
            name[$name:ident],
            max[$max:expr],
            debug_name[$($debug_name:expr)?],
        }
        @tokens {..}
    ) => { ... };
    (
        @with {
            attrs[$($attrs:meta)*],
            visibility[$visibility:vis],
            name[$name:ident],
            max[$max:expr],
            debug_name[$debug_name1:expr],
        }
        @tokens {
            debug_name[$($debug_name2:expr)?],
            $($tokens:tt)*
        }
    ) => { ... };
    (@with {
        attrs[$($attrs:meta)*],
        visibility[$visibility:vis],
        name[$name:ident],
        max[$max:expr],
        debug_name[$($debug_name:expr)?],
    }) => { ... };
    (
        @debug_impl {
            name[$name:ident],
            debug_name[]
        }
    ) => { ... };
    (
        @debug_impl {
            name[$name:ident],
            debug_name[$debug_name:expr]
        }
    ) => { ... };
}

Use to declare a "newtype'd" index that can be used with IndexVec. The simplest usage is just:

ⓘThis example is not tested
index_type! {
    $v struct Foo { .. }
}

where $v is whatever visibility you want (pub, crate, etc).

Instances offer several methods and also implement a number of convenient traits:

  • Foo::new(22) -- make a new Foo from a usize (works in constants, too)
  • Foo::from_u32(22) -- make a Foo from a u32 (works in constants, too)
  • foo.as_u32() -- extract the inner value as a u32
  • foo.as_usize() -- extract the inner value as a usize
  • Foo: From<usize> -- you can also use the From trait to construct from a usize
  • Foo: From<u32> -- ...or a u32

Index types also implement the usual suspects (Copy, Clone, Debug, PartialOrd, Ord, PartialEq, Eq, Hash) so they can be used with maps and things.

Storage

Internally, index types use a NonZeroU32 for storage. This means that they cannot exceed 2^32 - 1 in value (the code will assert this at runtime). It also means that Option<Foo> is just one u32 in size.

Configuring the newtype

Before the .. you can also add some configuration options. Example:

ⓘThis example is not tested
index_type! {
    struct Foo {
        debug_name[Bar],
        .. // <-- NB always end with `..`
    }
}

The options are:

  • debug_name[$expr] -- change how the Debug impl prints out. This should be a string expression, like "XXX". We will print "XXX"(N) where N is the index. If you put just debug_name[], then we will not emit any Debug impl at all, and you can provide your own.