# ShouldBe

## Objects

`ShouldBeExamples` works on all types and compares using `.Equals`.

```cs
var theSimpsonsCat = new Cat { Name = "Santas little helper" };
theSimpsonsCat.Name.ShouldBe("Snowball 2");
```

[snippet source](https://github.com/shouldly/shouldly/blob/master/src/DocumentationExamples/ShouldBeExamples.cs#L14-L19) | [anchor](#snippet-ShouldBeObjects)

**Exception**

```
theSimpsonsCat.Name
    should be
"Snowball 2"
    but was
"Santas little helper"
    difference
Difference     |       |    |    |    |    |    |         |    |    |    |    |    |    |    |    |    |    |    |   
               |      \|/  \|/  \|/  \|/  \|/  \|/       \|/  \|/  \|/  \|/  \|/  \|/  \|/  \|/  \|/  \|/  \|/  \|/  
Index          | 0    1    2    3    4    5    6    7    8    9    10   11   12   13   14   15   16   17   18   19   
Expected Value | S    n    o    w    b    a    l    l    \s   2                                                      
Actual Value   | S    a    n    t    a    s    \s   l    i    t    t    l    e    \s   h    e    l    p    e    r    
Expected Code  | 83   110  111  119  98   97   108  108  32   50                                                     
Actual Code    | 83   97   110  116  97   115  32   108  105  116  116  108  101  32   104  101  108  112  101  114  
```

## Numeric

`ShouldBe` numeric overloads accept tolerances and has overloads for `float`, `double` and `decimal` types.

```cs
const decimal pi = (decimal)Math.PI;
pi.ShouldBe(3.24m, 0.01m);
```

[snippet source](https://github.com/shouldly/shouldly/blob/master/src/DocumentationExamples/CodeExamples/ShouldBeExamples.Numeric.codeSample.approved.cs#L1-L2) | [anchor](#snippet-ShouldBeExamples.Numeric.codeSample.approved.cs)

**Exception**

```
pi
    should be within
0.01m
    of
3.24m
    but was
3.14159265358979m
```

## DateTime(Offset)

DateTime overloads are similar to the numeric overloads and support tolerances.

```cs
var date = new DateTime(2000, 6, 1);
date.ShouldBe(new(2000, 6, 1, 1, 0, 1), TimeSpan.FromHours(1));
```

[snippet source](https://github.com/shouldly/shouldly/blob/master/src/DocumentationExamples/CodeExamples/ShouldBeExamples.DateTime.codeSample.approved.cs#L1-L2) | [anchor](#snippet-ShouldBeExamples.DateTime.codeSample.approved.cs)

**Exception**

```
date
    should be within
01:00:00
    of
2000-06-01T01:00:01.0000000
    but was
2000-06-01T00:00:00.0000000
```

## TimeSpan

TimeSpan also has tolerance overloads

```cs
var timeSpan = TimeSpan.FromHours(1);
timeSpan.ShouldBe(timeSpan.Add(TimeSpan.FromHours(1.1d)), TimeSpan.FromHours(1));
```

[snippet source](https://github.com/shouldly/shouldly/blob/master/src/DocumentationExamples/CodeExamples/ShouldBeExamples.TimeSpanExample.codeSample.approved.cs#L1-L2) | [anchor](#snippet-ShouldBeExamples.TimeSpanExample.codeSample.approved.cs)

**Exception**

```
timeSpan
    should be within
01:00:00
    of
02:06:00
    but was
01:00:00
```

## Enumerables

Enumerable comparison is done on the elements in the enumerable, so you can compare an array to a list and have it pass.

```cs
var apu = new Person { Name = "Apu" };
var homer = new Person { Name = "Homer" };
var skinner = new Person { Name = "Skinner" };
var barney = new Person { Name = "Barney" };
var theBeSharps = new List<Person> { homer, skinner, barney };
theBeSharps.ShouldBe(new[] { apu, homer, skinner, barney });
```

[snippet source](https://github.com/shouldly/shouldly/blob/master/src/DocumentationExamples/CodeExamples/ShouldBeExamples.Enumerables.codeSample.approved.cs#L1-L6) | [anchor](#snippet-ShouldBeExamples.Enumerables.codeSample.approved.cs)

**Exception**

```
theBeSharps
    should be
[Apu, Homer, Skinner, Barney]
    but was
[Homer, Skinner, Barney]
    difference
[*Homer*, *Skinner*, *Barney*, *]
```

## Enumerables of Numerics

If you have enumerables of `float`, `decimal` or `double` types then you can use the tolerance overloads, similar to the value extensions.

```cs
var firstSet = new[] { 1.23m, 2.34m, 3.45001m };
var secondSet = new[] { 1.4301m, 2.34m, 3.45m };
firstSet.ShouldBe(secondSet, 0.1m);
```

[snippet source](https://github.com/shouldly/shouldly/blob/master/src/DocumentationExamples/CodeExamples/ShouldBeExamples.EnumerablesOfNumerics.codeSample.approved.cs#L1-L3) | [anchor](#snippet-ShouldBeExamples.EnumerablesOfNumerics.codeSample.approved.cs)

**Exception**

```
firstSet
    should be within
0.1m
    of
[1.4301m, 2.34m, 3.45m]
    but was
[1.23m, 2.34m, 3.45001m]
    difference
[*1.23m*, 2.34m, *3.45001m*]
```

## Bools

```cs
const bool myValue = false;
myValue.ShouldBe(true, "Some additional context");
```

[snippet source](https://github.com/shouldly/shouldly/blob/master/src/DocumentationExamples/CodeExamples/ShouldBeExamples.BooleanExample.codeSample.approved.cs#L1-L2) | [anchor](#snippet-ShouldBeExamples.BooleanExample.codeSample.approved.cs)

**Exception**

```
myValue
    should be
True
    but was
False

Additional Info:
    Some additional context
```