== Why is this an issue?

When the call to a function doesn't have any side effects, what is the point of making the call if the results are ignored? In such case, either the function call is useless and should be dropped or the source code doesn't behave as expected.


To prevent generating any false-positives, this rule triggers an issue only on the following predefined list of immutable classes in the Java API :

* ``++java.lang.String++``
* ``++java.lang.Boolean++``
* ``++java.lang.Integer++``
* ``++java.lang.Double++``
* ``++java.lang.Float++``
* ``++java.lang.Byte++``
* ``++java.lang.Character++``
* ``++java.lang.Short++``
* ``++java.lang.StackTraceElement++``
* ``++java.time.DayOfWeek++``
* ``++java.time.Duration++``
* ``++java.time.Instant++``
* ``++java.time.LocalDate++``
* ``++java.time.LocalDateTime++``
* ``++java.time.LocalTime++``
* ``++java.time.Month++``
* ``++java.time.MonthDay++``
* ``++java.time.OffsetDateTime++``
* ``++java.time.OffsetTime++``
* ``++java.time.Period++``
* ``++java.time.Year++``
* ``++java.time.YearMonth++``
* ``++java.time.ZonedDateTime++``
* ``++java.math.BigInteger++``
* ``++java.math.BigDecimal++``
* ``++java.util.Optional++``

As well as methods of the following classes:

* ``++java.util.Collection++``:
** ``++size()++``
** ``++isEmpty()++``
** ``++contains(...)++``
** ``++containsAll(...)++``
** ``++iterator()++``
** ``++toArray()++``

* ``++java.util.Map++``:
** ``++size()++``
** ``++isEmpty()++``
** ``++containsKey(...)++``
** ``++containsValue(...)++``
** ``++get(...)++``
** ``++getOrDefault(...)++``
** ``++keySet()++``
** ``++entrySet()++``
** ``++values()++``

* ``++java.util.stream.Stream++``
** ``++toArray++``
** ``++reduce++``
** ``++collect++``
** ``++min++``
** ``++max++``
** ``++count++``
** ``++anyMatch++``
** ``++allMatch++``
** ``++noneMatch++``
** ``++findFirst++``
** ``++findAny++``
** ``++toList++``

=== Noncompliant code example

[source,java]
----
public void handle(String command){
  command.toLowerCase(); // Noncompliant; result of method thrown away
  ...
}
----

=== Compliant solution

[source,java]
----
public void handle(String command){
  String formattedCommand = command.toLowerCase();
  ...
}
----

=== Exceptions

This rule will not raise an issue when both these conditions are met:

* The method call is in a ``++try++`` block with an associated ``++catch++`` clause.
* The method name starts with "parse", "format", "decode" or "valueOf" or the method is ``++String.getBytes(Charset)++``.

[source,java]
----
private boolean textIsInteger(String textToCheck) {

    try {
        Integer.parseInt(textToCheck, 10); // OK
        return true;
    } catch (NumberFormatException ignored) {
        return false;
    }
}
----

== Resources

* https://wiki.sei.cmu.edu/confluence/x/xzdGBQ[CERT, EXP00-J.] - Do not ignore values returned by methods

ifdef::env-github,rspecator-view[]

'''
== Implementation Specification
(visible only on this page)

include::../message.adoc[]

'''
== Comments And Links
(visible only on this page)

=== on 12 Aug 2019, 23:58:32 Andreas Knees wrote:
I suggest an Exception for this rule.


I use this code to determine whether a number has the desired number of fraction digits:


----
BigDecimal bd = new BigDecimal("12.00");
try {

    bd.setScale(allowedFractionDigits);

} catch (final ArithmeticException ex) {
        // thrown if the specified scaling operation would require
        // rounding.
        if (allowedFractionDigits == 0) {
            putError("validation.number.integer");
        } else {
            putError("validation.number.fractionDigits", allowedFractionDigits);
        }
}
----

So in my opinion ``++BigDecimal.setScale(int)++`` should be excluded from this rule, because I don't use and don't need the return value in this case.

include::../comments-and-links.adoc[]

endif::env-github,rspecator-view[]
