#37 javadoc: text

assira.core/src/main/java/net/ranides/assira/text/Charsets.java

@@ -6,35 +6,72 @@
  */
 package net.ranides.assira.text;
 
+import lombok.experimental.UtilityClass;
+
 import java.nio.charset.Charset;
 import java.nio.charset.StandardCharsets;
 
+/**
+ * Class with charset constansts.
+ *
+ * {@link StandardCharsets} class does not have some constants defined here.
+ */
+@UtilityClass
 public final class Charsets {
-    
-    private Charsets() {
-        // utility class        
-    }
 
+    /**
+     * ISO646-US 7-bit charset
+     */
     public static final Charset US_ASCII = StandardCharsets.US_ASCII;
 
+    /**
+     * ISO-LATIN-1
+     */
     public static final Charset ISO88591 = StandardCharsets.ISO_8859_1;
 
+    /**
+     * UTF-8
+     */
     public static final Charset UTF8 = StandardCharsets.UTF_8;
 
+    /**
+     * UTF-16 big-endian
+     */
     public static final Charset UTF16BE = StandardCharsets.UTF_16BE;
 
+    /**
+     * UTF-16 little-endian
+     */
     public static final Charset UTF16LE = StandardCharsets.UTF_16LE;
 
+    /**
+     * UTF-16 with byte order mark
+     */
     public static final Charset UTF16 = StandardCharsets.UTF_16;
-    
+
+    /**
+     * UTF-32 with byte order mark
+     */
     public static final Charset UTF32 = Charset.forName("UTF-32");
 
+    /**
+     * IBM852: polish MS-DOS charset
+     */
     public static final Charset PL_DOS = Charset.forName("IBM852");
 
+    /**
+     * ISO-8859-2: polish "internet" charset
+     */
     public static final Charset PL_ISO = Charset.forName("ISO-8859-2");
 
+    /**
+     * windows-1250: polish windows charset
+     */
     public static final Charset PL_WINDOWS = Charset.forName("windows-1250");
 
+    /**
+     * Mazovia: ancient unofficial polish charset
+     */
     public static final Charset MAZOVIA = MazoviaCharset.CHARSET;
 
 }

assira.core/src/main/java/net/ranides/assira/text/FormatBase64.java

@@ -4,13 +4,28 @@ import lombok.experimental.UtilityClass;
 
 import java.util.Base64;
 
+/**
+ * Basic base64 methods built on top of {@link Base64}
+ */
 @UtilityClass
 public class FormatBase64 {
 
+    /**
+     * Encodes binary data to String using basic scheme (no line separators)
+     *
+     * @param data data
+     * @return data
+     */
     public static String format(byte[] data) {
         return Base64.getEncoder().encodeToString(data);
     }
 
+    /**
+     * Decodes string using basic base64 scheme into binary data
+     *
+     * @param data data
+     * @return data
+     */
     public static byte[] parse(String data) {
         return Base64.getDecoder().decode(data);
     }

assira.core/src/main/java/net/ranides/assira/text/FormatHex.java

@@ -49,10 +49,25 @@ public final class FormatHex {
         CH_TABLE['f'] = 15;
     }
 
+    /**
+     * Encodes bytes into list of hexadecimal numbers separated by spaces.
+     *
+     * @param raw raw
+     * @return String
+     */
     public static String format(byte[] raw) {
         return format(new StrBuffer(3*raw.length), raw).toString();
     }
 
+    /**
+     * Encodes bytes into list of hexadecimal numbers separated by spaces.
+     * Generated result is inserted into "target" buffer.
+     *
+     * @param target target
+     * @param raw raw
+     * @param <T> T
+     * @return target
+     */
     public static <T extends Appendable> T format(T target, byte[] raw) {
         try {
             int n= raw.length;
@@ -69,6 +84,13 @@ public final class FormatHex {
         }
     }
 
+    /**
+     * Encodes byte into 2-digit hexadecimal number.
+     * Generated result is inserted into "target" buffer.
+     *
+     * @param target target
+     * @param value value
+     */
     public static void appendByte(Appendable target, byte value) {
         try {
             int ivalue = value & 0xFF;
@@ -79,6 +101,13 @@ public final class FormatHex {
         }
     }
 
+    /**
+     * Encodes char into 4-digit hexadecimal number.
+     * Generated result is inserted into "target" buffer.
+     *
+     * @param target target
+     * @param value value
+     */
     public static void appendChar(Appendable target, char value) {
         try {
             int ivalue = value & 0xFFFF;
@@ -91,15 +120,30 @@ public final class FormatHex {
         }
     }
 
-    public static char parseChar(CharSequence text, int index) {
-        byte a = CH_TABLE[text.charAt(index++)];
-        byte b = CH_TABLE[text.charAt(index++)];
-        byte c = CH_TABLE[text.charAt(index++)];
-        byte d = CH_TABLE[text.charAt(index++)];
+    /**
+     * Takes 4 characters from "text" and converts extracted 4-digit hexadecimal number into char.
+     *
+     * Starts reading characters at "offset".
+     *
+     * @param text text
+     * @param offset offset
+     * @return char
+     */
+    public static char parseChar(CharSequence text, int offset) {
+        byte a = CH_TABLE[text.charAt(offset++)];
+        byte b = CH_TABLE[text.charAt(offset++)];
+        byte c = CH_TABLE[text.charAt(offset++)];
+        byte d = CH_TABLE[text.charAt(offset++)];
 
         return (char) ((a << 12) | (b << 8) | (c << 4) | (d));
     }
 
+    /**
+     * Converts list of 2-digit hexadecimal numbers separated by spaces into bytes.
+     *
+     * @param text text
+     * @return bytes
+     */
     public static byte[] parse(CharSequence text) {
         int bytes = (text.length()+1) / 3;
         byte[] target = new byte[bytes];

assira.core/src/main/java/net/ranides/assira/text/FormatNumber.java

@@ -9,17 +9,16 @@ package net.ranides.assira.text;
 import java.math.BigDecimal;
 import java.util.IllegalFormatConversionException;
 import java.util.Locale;
+
+import lombok.experimental.UtilityClass;
 import net.ranides.assira.collection.maps.IntMap;
 
 /**
  *
  * @author ranides
  */
+@UtilityClass
 public final class FormatNumber {
-    
-    private FormatNumber() {
-        /* utility class */ 
-    }
 
     // metric (SI)
     private static final char MP_K = 'M';
@@ -118,6 +117,14 @@ public final class FormatNumber {
     };
 
     /**
+     * Converts number into string using specified format.
+     *
+     * Format is "printf-compatible" and is defines number precision and unit prefixes.
+     * Please read: https://en.wikipedia.org/wiki/Engineering_notation
+     *
+     * For example {@code %2.3M} means metric prefix.
+     * If you pass number 16450200, you will receive "16.450M"
+     *
      * Supported formats (unit prefixes): 
      * <ul>
      *      <li>M (metric, SI prefix)</li>
@@ -126,6 +133,7 @@ public final class FormatNumber {
      *      <li>K (binary, Donald Knuth prefix)</li>
      *      <li>B (binary, exponent)</li>
      * </ul>
+     *
      * @param format "printf-compatible" number format, e.g {@code %2.5M}
      * @param value
      * @return 
@@ -135,6 +143,15 @@ public final class FormatNumber {
     }
 
     /**
+     * Converts number into string using specified format.
+     * Result is appended to provided "target" buffer.
+     *
+     * Format is "printf-compatible" and is defines number precision and unit prefixes.
+     * Please read: https://en.wikipedia.org/wiki/Engineering_notation
+     *
+     * For example {@code %2.3M} means metric prefix.
+     * If you pass number 16450200, you will receive "16.450M"
+     *
      * Supported formats (unit prefixes): 
      * <ul>
      *      <li>M (metric, SI prefix)</li>
@@ -185,11 +202,23 @@ public final class FormatNumber {
             default: return null;
         }
     }
-    
+
+    /**
+     * Converts number to string, separating 3-digit groups by ' character.
+     *
+     * @param value value
+     * @return String
+     */
     public static String group(int value) {
         return group(Integer.toString(value, 10), "'");
     }
 
+    /**
+     * Converts number to string, separating 3-digit groups by ' character.
+     *
+     * @param value value
+     * @return String
+     */
     public static String group(long value) {
         return group(Long.toString(value, 10), "'");
     }

assira.core/src/main/java/net/ranides/assira/text/IOStrings.java

@@ -24,32 +24,73 @@ import java.nio.file.Path;
 import java.util.ArrayList;
 import java.util.Iterator;
 import java.util.List;
+
+import lombok.experimental.UtilityClass;
 import net.ranides.assira.collection.arrays.ArrayAllocator;
 
 /**
+ * Utility methods for quick read/write text into files and streams.
  *
  * @author ranides
  */
+@UtilityClass
 public final class IOStrings {
-    
-    private IOStrings() { }
 
+    /**
+     * Opens provided file for reading, returns Reader using provided charset
+     *
+     * @param path path
+     * @param cs cs
+     * @return Reader
+     * @throws IOException on error
+     */
     public static Reader reader(Path path, Charset cs) throws IOException {
         return reader(path.toFile(), cs);
     }
-    
+
+    /**
+     * Opens provided file for reading, returns Reader using provided charset
+     *
+     * @param file file
+     * @param cs cs
+     * @return Reader
+     * @throws IOException on error
+     */
     public static Reader reader(File file, Charset cs) throws IOException {
         return new InputStreamReader(new FileInputStream(file), cs);
     }
 
+    /**
+     * Opens provided file for write, returns Writer using provided charset
+     *
+     * @param path path
+     * @param cs cs
+     * @return Writer
+     * @throws IOException on error
+     */
     public static Writer writer(Path path, Charset cs) throws IOException {
         return writer(path.toFile(), cs);
     }
-    
+
+    /**
+     * Opens provided file for write, returns Writer using provided charset
+     *
+     * @param file file
+     * @param cs cs
+     * @return Writer
+     * @throws IOException on error
+     */
     public static Writer writer(File file, Charset cs) throws IOException {
         return new OutputStreamWriter(new FileOutputStream(file), cs);
     }
 
+    /**
+     * Writes down content to writer and closes it.
+     *
+     * @param writer writer
+     * @param content content
+     * @throws IOException on error
+     */
 	public static void write(Writer writer, String content) throws IOException {
 		try {
 			writer.write(content);
@@ -57,7 +98,15 @@ public final class IOStrings {
 			writer.close();
 		}
 	}
-	
+
+    /**
+     * Writes down content to stream and closes it.
+     *
+     * @param ostream ostream
+     * @param content content
+     * @param charset charset
+     * @throws IOException on error
+     */
 	public static void write(OutputStream ostream, String content, Charset charset) throws IOException {
 		try {	
 			write(new OutputStreamWriter(ostream, charset), content);
@@ -65,15 +114,38 @@ public final class IOStrings {
 			ostream.close();
 		}
 	}
-	
+
+    /**
+     * Writes down content to file.
+     *
+     * @param path path
+     * @param content content
+     * @param charset charset
+     * @throws IOException on error
+     */
 	public static void write(Path path, String content, Charset charset) throws IOException {
         write(path.toFile(), content, charset);
     }
-    
-	public static void write(File file, String content, Charset charset) throws IOException {
+
+    /**
+     * Writes down content to file.
+     *
+     * @param file file
+     * @param content content
+     * @param charset charset
+     * @throws IOException on error
+     */
+    public static void write(File file, String content, Charset charset) throws IOException {
 		write(new FileOutputStream(file), content, charset);
 	}
 
+    /**
+     * Reads all content from reader and closes it
+     *
+     * @param reader reader
+     * @return String
+     * @throws IOException on error
+     */
     public static String read(Reader reader) throws IOException {
         try {
             char[] buffer = new char[32];
@@ -88,6 +160,14 @@ public final class IOStrings {
         }
     }
 
+    /**
+     * Reads all content from stream and closes it
+     *
+     * @param istream istream
+     * @param charset charset
+     * @return String
+     * @throws IOException on error
+     */
     public static String read(InputStream istream, Charset charset) throws IOException {
         try {
             return IOStrings.read(new InputStreamReader(istream, charset));
@@ -96,14 +176,38 @@ public final class IOStrings {
         }
     }
 
+    /**
+     * Reads all content from file
+     *
+     * @param path path
+     * @param charset charset
+     * @return String
+     * @throws IOException on error
+     */
     public static String read(Path path, Charset charset) throws IOException {
         return read(path.toFile(), charset);
     }
-    
+
+    /**
+     * Reads all content from file
+     *
+     * @param file file
+     * @param charset charset
+     * @return String
+     * @throws IOException on error
+     */
     public static String read(File file, Charset charset) throws IOException {
         return read( new FileInputStream(file), charset );
     }
 
+    /**
+     * Reads all lines from reader and closes it.
+     * Every newline format is supported.
+     *
+     * @param ireader ireader
+     * @return lines
+     * @throws IOException on error
+     */
     public static List<String> readLines(Reader ireader) throws IOException {
         ArrayList<String> result = new ArrayList<>();
         try (BufferedReader reader = new BufferedReader(ireader)) {
@@ -115,19 +219,54 @@ public final class IOStrings {
         result.trimToSize();
         return result;
     }
-    
+
+    /**
+     * Reads all lines from stream and closes it.
+     * Every newline format is supported.
+     *
+     * @param istream istream
+     * @param charset charset
+     * @return lines
+     * @throws IOException on error
+     */
     public static List<String> readLines(InputStream istream, Charset charset) throws IOException {
         return readLines(new BufferedReader(new InputStreamReader(istream, charset)));
     }
-    
+
+    /**
+     * Reads all lines from file.
+     * Every newline format is supported.
+     *
+     * @param path path
+     * @param charset charset
+     * @return lines
+     * @throws IOException on error
+     */
     public static List<String> readLines(Path path, Charset charset) throws IOException {
         return Files.readAllLines(path, charset);
     }
-    
+
+    /**
+     * Reads all lines from file.
+     * Every newline format is supported.
+     *
+     * @param file file
+     * @param charset charset
+     * @return lines
+     * @throws IOException on error
+     */
     public static List<String> readLines(File file, Charset charset) throws IOException {
         return readLines(new FileInputStream(file), charset);
     }
-    
+
+    /**
+     * Writes all lines into writer and closes it.
+     * Uses system dependent line separator.
+     *
+     * @param iwriter iwriter
+     * @param content content
+     * @throws IOException on error
+     */
     public static void writeLines(Writer iwriter, Iterator<String> content) throws IOException {
         try(BufferedWriter writer = new BufferedWriter(iwriter)) {
             while(content.hasNext()) {
@@ -136,31 +275,93 @@ public final class IOStrings {
             }
         }
     }
-    
+
+    /**
+     * Writes all lines into stream and closes it.
+     * Uses system dependent line separator.
+     *
+     * @param ostream ostream
+     * @param charset charset
+     * @param content content
+     * @throws IOException on error
+     */
     public static void writeLines(OutputStream ostream, Charset charset, Iterator<String> content) throws IOException {
         writeLines(new OutputStreamWriter(ostream, charset), content);
     }
-    
+
+    /**
+     * Writes all lines into file.
+     * Uses system dependent line separator.
+     *
+     * @param path path
+     * @param charset charset
+     * @param content content
+     * @throws IOException on error
+     */
     public static void writeLines(Path path, Charset charset, Iterator<String> content) throws IOException {
         writeLines(path.toFile(), charset, content);
     }
-    
+
+    /**
+     * Writes all lines into file.
+     * Uses system dependent line separator.
+     *
+     * @param file file
+     * @param charset charset
+     * @param content content
+     * @throws IOException on error
+     */
     public static void writeLines(File file, Charset charset, Iterator<String> content) throws IOException {
         writeLines(new FileOutputStream(file), charset, content);
     }
-    
+
+    /**
+     * Writes all lines into writer and closes it.
+     * Uses system dependent line separator.
+     *
+     * @param iwriter iwriter
+     * @param content content
+     * @throws IOException on error
+     */
     public static void writeLines(Writer iwriter, Iterable<String> content) throws IOException {
         writeLines(iwriter, content.iterator());
     }
-    
+
+    /**
+     * Writes all lines into stream and closes it.
+     * Uses system dependent line separator.
+     *
+     * @param ostream ostream
+     * @param charset charset
+     * @param content content
+     * @throws IOException on error
+     */
     public static void writeLines(OutputStream ostream, Charset charset, Iterable<String> content) throws IOException {
         writeLines(ostream, charset, content.iterator());
     }
-    
+
+    /**
+     * Writes all lines into file.
+     * Uses system dependent line separator.
+     *
+     * @param path path
+     * @param charset charset
+     * @param content content
+     * @throws IOException on error
+     */
     public static void writeLines(Path path, Charset charset, Iterable<String> content) throws IOException {
         writeLines(path.toFile(), charset, content);
     }
-    
+
+    /**
+     * Writes all lines into file.
+     * Uses system dependent line separator.
+     *
+     * @param file file
+     * @param charset charset
+     * @param content content
+     * @throws IOException on error
+     */
     public static void writeLines(File file, Charset charset, Iterable<String> content) throws IOException {
         writeLines(file, charset, content.iterator());
     }

assira.core/src/main/java/net/ranides/assira/text/LexicalCast.java

@@ -18,18 +18,45 @@ import java.time.temporal.TemporalAccessor;
 import java.util.Date;
 
 /**
- * Klasa używana tylko do prezentowania obiektów jako tekst bardziej
- * reprezentatywnie niż za pomocą wbudowanych metod "toString".
+ * This class is used to cast objects using their values, not inheritance tree.
+ *
+ * Essentially, it works like you converted "value" into text and then parsed into target "clazz".
+ *
+ * Supports numbers, strings, boolean, dates, and objects constructible from String.
  *
  * @author ranides
  */
 @UtilityClass
 public final class LexicalCast {
 
-    public static <T> T cast(Object value, Class<T> clazz) throws ClassCastException {
+    /**
+     * Converts value into specified clazz.
+     *
+     * If target type is not built-in, it converts value using "toString" and
+     * constructs result passing this generated string to constructor.
+     *
+     * @param value value
+     * @param clazz clazz
+     * @param <T> T
+     * @return T
+     * @throws LexicalCastException if conversion is not supported
+     */
+    public static <T> T cast(Object value, Class<T> clazz) throws LexicalCastException {
         return cast(value, IClass.typeinfo(clazz));
     }
-    
+
+    /**
+     * Converts value into specified clazz.
+     *
+     * If target type is not built-in, it converts value using "toString" and
+     * constructs result passing this generated string to constructor.
+     *
+     * @param value value
+     * @param type type
+     * @param <T> T
+     * @return T
+     * @throws LexicalCastException if conversion is not supported
+     */
     @SuppressWarnings("unchecked")
     public static <T> T cast(Object value, IClass<T> type) throws LexicalCastException {
         return (T)rawcast(value, type);
@@ -86,7 +113,7 @@ public final class LexicalCast {
                 if("false".equalsIgnoreCase((String)value)) {
                     return false;
                 }
-                throw new LexicalCastException(value + " cannot is not valid boolean");
+                throw new LexicalCastException(value + " cannot be converted to boolean");
             }
         }
         // najpopularniejsze konwersje Number -> Number / String

assira.core/src/main/java/net/ranides/assira/text/MazoviaCharset.java

@@ -14,6 +14,10 @@ import java.util.Locale;
 import java.util.Set;
 import net.ranides.assira.collection.sets.OpenSet;
 
+/**
+ * Mazovia charset is ancient unofficial MS-DOS encoding for polish characters.
+ * This CharsetProvider registers itself under cp896, cp620 and cp790
+ */
 public class MazoviaCharset extends CharsetProvider {
 
     private static final String NAME = "mazovia";

assira.core/src/main/java/net/ranides/assira/text/NaturalComparator.java

@@ -32,17 +32,51 @@ import lombok.experimental.UtilityClass;
 import java.util.Comparator;
 import java.util.function.Function;
 
+/**
+ * NaturalComparator implements lexicographical ordering of strings, but with
+ * improved support for numbers.
+ *
+ * Classical lexicographical ordering sorts list of names:
+ *     name1, name10, name11, name3
+ *
+ * You must use digit padding, to achieve expected result:
+ *     name01, name03, name10, name11
+ *
+ * NaturalComparator does not require it and returns:
+ *     name1, name3, name10, name11
+ */
 @UtilityClass
 public class NaturalComparator {
 
+    /**
+     * Returns instance of NaturalComparator
+     *
+     * @return Comparator
+     */
     public static Comparator<String> comparator() {
         return NaturalComparator::compareTo;
     }
 
+    /**
+     * Returns NaturalComparator for objects T which first converts them to String
+     *
+     * @param map map
+     * @param <T> T
+     * @return Comparator
+     */
     public static <T> Comparator<T> comparator(Function<T, String> map) {
         return Comparator.comparing(map, comparator());
     }
 
+    /**
+     * Compares its two arguments for order.  Returns a negative integer,
+     * zero, or a positive integer as the first argument is less than, equal
+     * to, or greater than the second.
+     *
+     * @param a a
+     * @param b b
+     * @return int
+     */
     public static int compareTo(String a, String b) {
         int ia = 0, ib = 0;
         int nza, nzb;