Ever been stumped by <E>, <T>, <K, V> in OO language documentation?
Tags: dart, beginners, showdev, discuss
Published: 2018-12-27 18:14:48

Over on the Reddit [/r/dartlang](https://reddit.com/r/dartlang) group, an individual by the name of **NFC_TagsForDroid** reached out to me in regards to confusion navigating the Dart documentation. This was specifically when understanding the meaning behind some of the "tokens" used when demonstrating code samples.

Here's an extract from the user's comment:

>_Can you please write a explainer on how to read dartlang documentation? Most of it is meaningless to a beginner. For example: https://api.dartlang.org/stable/2.1.0/dart-core/List/add.html (Dart dart:core List\<E> add abstract method)
the heading List\<E> add abstract method **what is the \<E>**? how does it being an abstract method affect anything?_

The user is referring to the signature for the List type's `add()` method:

```dart
void add(
  E value
);
```

The source of confusion is the `E`. Others used in various documentation code samples are `T`, `K` and  `V`.

## So what do these mean?

These seemingly magical "tagged letters" are _placeholders_ that are used to represent what is known as a _type parameter_. This is common across _statically-typed_ object-oriented languages and will be apparent when it comes to the topic of **Generics**. 

Generics provide a way of telling the compiler what type is being used, so that it knows to check for that.

In other words if you see `<E>` read it as "of _**Type**_", so `List<String>` will be read as "List of _**String**_".

Now looking at that let's say we define a `List<E>`:

```dart
List<String> fruits = ['apple', 'orange', 'pineapple'];
```
Looking at the add method again:

```dart
void add(
  E value
);
```
The way to read this is that the `E` represents an **element** in the collection, whatever type **we initially specified when we created that list**! In the case of `fruits` its `String`.

And this is how we would use it:

```dart
fruits.add('mango');

fruits.add(1); // This will throw an error as it's the wrong type
```
## So why are particular letters used?

Simplest answer is _convention_. In fact you can use any letters you like, achieving the same effect. However the common ones carry semantic meaning:

* `T` is meant to be a Type
* `E` is meant to be an Element (`List<E>`: a list of Elements)
* `K` is Key (in a `Map<K, V>`)
* `V` is Value (as a return value or mapped value)

This code below will work even when I don't use any of the placeholder letters above. For example, see this snippet below:

```dart
class CacheItem<A> { // Using the letter A
  CacheItem(A this.itemToCache);

  final itemToCache;

  String get detail => '''
    Cached item: $itemToCache
    The item type is $A
  ''';
}

void main() {
  var cached = CacheItem<int>(1);
  print(cached.detail);
  // Output:
  // Cached item: 1
  // The item's type is int
}
```
→ [**Run in DartPad**](https://dartpad.dartlang.org/b2f2b4b80a52b3e83e074b10086e7a87)

This works although the placeholder used is `A`. By convention `T` would be used:

```dart
class CacheItem<T> {
  CacheItem(T this.itemToCache);

  final itemToCache;

  String get detail => '''
    Cached item: $itemToCache
    The item type is $T
  ''';
}
```

Generics are powerful in that they allow us to reuse the same class with various types:

```dart
CacheItem<String> cachedString = CacheItem<String>('Hello, World!');
print(cachedString.detail);
// Output:
// Cached item: Hello, World!
// The item's type is String

var cachedInt = CacheItem<int>(30);
print(cachedInt.detail);
// Output:
// Cached item: 30
// The item's type is int

var cachedBool = CacheItem<bool>(true);
print(cachedBool.detail);
// Output:
// Cached item: true
// The item's type is bool
```
I hope this was insightful and you learnt something new today.

## Further reading
* [StackOverflow post about Generics](https://stackoverflow.com/questions/6008241/what-is-the-difference-between-e-and-t-for-java-generics)
* [Language guide to generics](http://download.oracle.com/javase/1,5.0/docs/guide/language/generics.html)
* [**Free Dart Screencasts on Egghead.io**](https://egghead.io/instructors/jermaine-oppong)

---

## Sharing is caring 🤗

If you enjoyed reading this post, please share this through the various social channels. Also, check out and [**subscribe to my YouTube channel**](https://youtube.com/c/CreativeBracket) (hit the bell icon too) for videos on Dart.

[**Subscribe to my email newsletter**](http://eepurl.com/gipQBX) to download my Free 35-page **Get started with Dart** eBook and to be notified when new content is released.

**Like, share and [follow me](https://twitter.com/creativ_bracket)** 😍 for more content on Dart.