Promote renderResult method to public (#1801)

This small commit makes public the "renderResult" method of the
"QRCodeWriter" class.

    The reason to promote this method as public is that I'm facing
Business Case where, besides of generating the QR code as a PNG image,
I also need to print information about the QR code itself (specifically,
the QR version). Navigating through the code of zxing library, I noticed
that the com.google.zxing.qrcode.encoder.Encoder allows me to have that
(the QR metadata); however, by invoking that class I only have part of
the equation (the QRCode DTO) ... I'm still needing to generate the
BitMatrix in order to produce the QR image.

    Here, I have two alternatives: either I invoke the Encoder.encode
class by myself and repeat the same logic when invoking the
QRCodeWriter.encode method; or I make the renderResult Public, call the
Encoder.encode and then I proceed to call the QRCodeWriter.renderResult
method with the previous result.

core/src/main/java/com/google/zxing/qrcode/QRCodeWriter.java

@@ -79,9 +79,27 @@ public final class QRCodeWriter implements Writer {
     return renderResult(code, width, height, quietZone);
   }
 
-  // Note that the input matrix uses 0 == white, 1 == black, while the output matrix uses
-  // 0 == black, 255 == white (i.e. an 8 bit greyscale bitmap).
-  private static BitMatrix renderResult(QRCode code, int width, int height, int quietZone) {
+  /**
+   * Renders the given {@link QRCode} as a {@link BitMatrix}, scaling the
+   * same to be compliant with the provided dimensions.
+   *
+   * <p>If no scaling is required, both {@code width} and {@code height}
+   * arguments should be non-positive numbers.
+   *
+   * @param code {@code QRCode} to be adapted as a {@code BitMatrix}
+   * @param width desired width for the {@code QRCode} (in pixel units)
+   * @param height desired height for the {@code QRCode} (in pixel units)
+   * @param quietZone the size of the QR quiet zone (in pixel units)
+   * @return {@code BitMatrix} instance
+   *
+   * @throws IllegalStateException if {@code code} does not have
+   *      a {@link QRCode#getMatrix() Matrix}
+   *
+   * @throws NullPointerException if {@code code} is {@code null}
+   */
+  public static BitMatrix renderResult(QRCode code, int width, int height, int quietZone) {
+    // Note that the input matrix uses 0 == white, 1 == black, while the output matrix uses
+    // 0 == black, 255 == white (i.e. an 8 bit greyscale bitmap).
     ByteMatrix input = code.getMatrix();
     if (input == null) {
       throw new IllegalStateException();
@@ -114,5 +132,4 @@ public final class QRCodeWriter implements Writer {
 
     return output;
   }
-
 }

core/src/test/java/com/google/zxing/qrcode/QRCodeWriterTestCase.java

@@ -22,6 +22,9 @@ import com.google.zxing.Writer;
 import com.google.zxing.WriterException;
 import com.google.zxing.common.BitMatrix;
 import com.google.zxing.qrcode.decoder.ErrorCorrectionLevel;
+import com.google.zxing.qrcode.encoder.ByteMatrix;
+import com.google.zxing.qrcode.encoder.QRCode;
+
 import org.junit.Assert;
 import org.junit.Test;
 
@@ -133,4 +136,55 @@ public final class QRCodeWriterTestCase extends Assert {
         "renderer-test-01.png");
   }
 
+  @Test
+  public void renderResultScalesNothing() {
+    final int expectedSize = 33;           // Original Size (25) + quietZone
+    BitMatrix result;
+    ByteMatrix matrix;
+    QRCode code;
+
+    matrix = new ByteMatrix(25, 25);    // QR Version 2! It's all white 
+                                        // but it doesn't matter here
+
+    code = new QRCode();
+    code.setMatrix(matrix);
+
+    // Test:
+    result = QRCodeWriter.renderResult(code, -1, -1, 4);
+
+    assertNotNull(result);
+    assertEquals(result.getHeight(), expectedSize);
+    assertEquals(result.getWidth(), expectedSize);
+  }
+
+  @Test
+  public void renderResultScalesWhenRequired() {
+    final int expectedSize = 66;
+    BitMatrix result;
+    ByteMatrix matrix;
+    QRCode code;
+
+    matrix = new ByteMatrix(25, 25);    // QR Version 2! It's all white 
+                                        // but it doesn't matter here
+
+    code = new QRCode();
+    code.setMatrix(matrix);
+
+    // Test:
+    result = QRCodeWriter.renderResult(code, 66, 66, 4);
+
+    assertNotNull(result);
+    assertEquals(result.getHeight(), expectedSize);
+    assertEquals(result.getWidth(), expectedSize);
+  }
+
+  @Test(expected = NullPointerException.class)
+  public void renderResultThrowsExIfCcodeIsNull() {
+    QRCodeWriter.renderResult(null, 0, 0, 0);
+  }
+
+  @Test(expected = IllegalStateException.class)
+  public void renderResultThrowsExIfCodeIsIncomplete() {
+    QRCodeWriter.renderResult(new QRCode(), 0, 0, 0);
+  }
 }