Merge pull request #3314 from vipulrawat/doc-additions-vipul

Improved docs and examples of nfs() and nf()

Author: lmccart

src/utilities/string_functions.js

@@ -134,6 +134,11 @@ p5.prototype.matchAll = function(str, reg) {
  * versions: one for formatting floats, and one for formatting ints.
  * The values for the digits, left, and right parameters should always
  * be positive integers.
+ * (NOTE): Be cautious when using left and right parameters as it prepends numbers of 0's if the parameter
+ * if greater than the current length of the number.
+ * For example if number is 123.2 and left parameter passed is 4 which is greater than length of 123
+ * (integer part) i.e 3 than result will be 0123.2. Same case for right parameter i.e. if right is 3 than
+ * the result will be 123.200.
  *
  * @method nf
  * @param {Number|String}       num      the Number to format
@@ -146,30 +151,31 @@ p5.prototype.matchAll = function(str, reg) {
  * @example
  * <div>
  * <code>
+ * var myFont;
+ * function preload() {
+ *   myFont = loadFont('assets/fonts/inconsolata.ttf');
+ * }
  * function setup() {
  *   background(200);
- *   var num = 112.53106115;
+ *   var num1 = 321;
+ *   var num2 = -1321;
  *
  *   noStroke();
  *   fill(0);
- *   textSize(14);
- *   // Draw formatted numbers
- *   text(nf(num, 5, 2), 10, 20);
- *
- *   text(nf(num, 4, 3), 10, 55);
- *
- *   text(nf(num, 3, 6), 10, 85);
+ *   textFont(myFont);
+ *   textSize(22);
  *
- *   // Draw dividing lines
+ *   text(nf(num1, 4, 2), 10, 30);
+ *   text(nf(num2, 4, 2), 10, 80);
+ *   // Draw dividing line
  *   stroke(120);
- *   line(0, 30, width, 30);
- *   line(0, 65, width, 65);
+ *   line(0, 50, width, 50);
  * }
  * </code>
  * </div>
  *
  * @alt
- * "0011253" top left, "0112.531" mid left, "112.531061" bottom left canvas
+ * "0321.00" middle top, -1321.00" middle bottom canvas
  */
 /**
  * @method nf
@@ -374,10 +380,18 @@ function addNfp(num) {
 
 /**
  * Utility function for formatting numbers into strings. Similar to <a href="#/p5/nf">nf()</a> but
- * puts a " " (space) in front of positive numbers and a "-" in front of
- * negative numbers. There are two versions: one for formatting floats, and
- * one for formatting ints. The values for the digits, left, and right
- * parameters should always be positive integers.
+ * puts an additional "_" (space) in front of positive numbers just in case to align it with negative
+ * numbers which includes "-" (minus) sign.
+ * The main usecase of nfs() can be seen when one wants to align the digits (place values) of a positive
+ * number with some negative number (See the example to get a clear picture).
+ * There are two versions: one for formatting float, and one for formatting int.
+ * The values for the digits, left, and right parameters should always be positive integers.
+ * (IMP): The result on the canvas basically the expected alignment can vary based on the typeface you are using.
+ * (NOTE): Be cautious when using left and right parameters as it prepends numbers of 0's if the parameter
+ * if greater than the current length of the number.
+ * For example if number is 123.2 and left parameter passed is 4 which is greater than length of 123
+ * (integer part) i.e 3 than result will be 0123.2. Same case for right parameter i.e. if right is 3 than
+ * the result will be 123.200.
  *
  * @method nfs
  * @param {Number}       num      the Number to format
@@ -390,19 +404,27 @@ function addNfp(num) {
  * @example
  * <div>
  * <code>
+ * var myFont;
+ * function preload() {
+ *   myFont = loadFont('assets/fonts/inconsolata.ttf');
+ * }
  * function setup() {
  *   background(200);
- *   var num1 = 11253106.115;
- *   var num2 = -11253106.115;
+ *   var num1 = 321;
+ *   var num2 = -1321;
  *
  *   noStroke();
  *   fill(0);
- *   textSize(12);
- *   // Draw formatted numbers
+ *   textFont(myFont);
+ *   textSize(22);
+ *
+ *   // nfs() aligns num1 (positive number) with num2 (negative number) by
+ *   // adding a blank space in front of the num1 (positive number)
+ *   // [left = 4] in num1 add one 0 in front, to align the digits with num2
+ *   // [right = 2] in num1 and num2 adds two 0's after both numbers
+ *   // To see the differences check the example of nf() too.
  *   text(nfs(num1, 4, 2), 10, 30);
- *
  *   text(nfs(num2, 4, 2), 10, 80);
- *
  *   // Draw dividing line
  *   stroke(120);
  *   line(0, 50, width, 50);
@@ -411,7 +433,7 @@ function addNfp(num) {
  * </div>
  *
  * @alt
- * "11253106.11" top middle and "-11253106.11" displayed bottom middle
+ * "0321.00" top middle and "-1321.00" displayed bottom middle
  */
 /**
  * @method nfs