Java package utils.casts

This package holds classes for boxing (wrapping) simple data types (currently only the class IntBox for boxing an int is implemented). In contrary to the Inbuild Integer class, the boxed int is not final. So IntBox may be used to pass arguments by reference to methods.

The class IntBox has a static method tryParse as C#:

static boolean IntBox.tryParse(String intString, IntBox intBox)

Currently the full "package" for the IntelliJ Gradle project can only be found on GitHub (just source, *.jar and *class file[s] see below):

https://github.com/psulzer/casts

You can download files from GitHub even if you haven't Git installed!

But cause it is a Gradle project inside JetBrains IntelliJ, I strongly recommend to check it out inside IntelliJ. I have checked it out into another directory and could recompile it successfully. Unfortunately you must create the "Edit configurations" in the "Run" menu. I don't know how to get them into the repo. If you cannot check it out please write (see Impressum on my homepage).

Currently normally only the IntBox_setTest1 configuration is needed to run the unit tests. Choose "Junit" in the left listbox (under Defaults) and fill the configuration dialog (see below, of course you must adjust the directory and file names, depending in which directory you check it out).


If you just want to use this package (currently only class IntBox), here are the downloads .jar, .class and the 2 source files [IntBox.java and IntBox_setTest1.java]):

utils_casts.zip as ZIP-archive for Java (with source, class and jar files)
(81 x downloaded)

The rest of this document is the top comment of the class IntBox.java:

/** IntBox class for Java published under the GNU General Public Licence
* (GPL) version 1 or any newer version
*
* Developers(!): Please read the end of this Java-Doc(!)
*
* Class that holds exactly one int (e. g. for reference passing to methods).
* IntBox objects will always hold a regular int (and not null - see
* exclusion/example below). Default value (with default constructor) is 0.
* This is achieved as there are no public constructors but only static
* fabric methods (have nothing to do with the design pattern "fabric method"
* from the "Gang of Four").
*
* All methods which will return an IntBox object will return an object
* which boxes a correct int. There are no methods which can fail (throw
* an exception). I. e. there are no methods like set(long l), instead
* call set(int i) with "intBox.set((int)l);" (where you are responsible
* for what you are doing ;-)) or (better) use the
* set(long l, int defaultValue) method.
*
* Following for example will not compile:
* IntBox ib;
* ...
* int i = IntBox.tryParse("Dummy",ib);
*
* Unfortunately the following cannot be prevented :-(
* ib = null; //(WHY WANT YOU DO THAT!, The makeIntBox(...)
* // methods always return an IntBox object(!).
* ...
* int j = ib.set("123"); // Boom...
*
* Usage:
*
* The most beneficial use of this class is to implement the static version
* of the C#-functions Type.TryParse(string s,Type t) into Java (unfortunately
* currently just implemented for an int).
*
* There is one difference to Integer.parse(String s) from Java: The tryParse
* functions accept leading and trailing whitespace. E. g.
* s=" 123 " will be parsed to 123, with Integer.parseInt(...) an
* exception will be thrown. In contrary to (e. g.) scanf(...) (C) or
* cin >> input (C++) s="123someNoneWhiteSpaceCharacters" will not be parsed
* to 123, but tryParse(...) will return false and the IntBox-argument will
* not be changed (even if it is null).
*
* Speed:
* The tryParse function is slightly faster than the standard java method
* int i=Integer.parseInt(String s), even when used without any error
* checking (try { Integer.parseInt... } catch ...
*
* Here are the results for some benchmark tests I run:
*
* All tests together (result of last loop) result in milli seconds:
* Integer.parseInt | 468 (standard Java parsing)
* tryParseException | 532 (commented out)
* tryParseWithTable | 562 (may be useful for CPUs with slow mult-op)
* tryParseForward | 453 (commented out)
* tryParse | 438
* tryParseForwardAssign | 437 (after tryParse an int is assigned, e. g.:
* tryParseAssign | 422 if (IntBox.tryParse(s,intBox)) i=intBox.v();)

* Hint: The times are varying in different runs. Sometimes
* tryParseForward is faster. As you can see above it even
* happened that the two Assign-methods were faster than the
* corresponding methods without Assign(!), albeit the former
* have an extra assignment statement for the int variable.
* Strange... But in general the trend was that tryParse (backward
* parsing) is the fastest method. The tryParse methods are highly
* optimized for speed (not for memory usage) and are not recommended
* for educational purposes (how to parse a string to an int value).
*
* Note:
* There is a function IntBox.tryParseWithTable(string s, IntBox intBox) which
* may be useful on CPUs without or slow multiplication operation. See the
* comment before the implementation of the function. On modern Intel processors
* this function is slower than tryParse(...). Another implementation
* tryParseForward(...) has been commented out, as it showed in a separate
* benchmark program, that it is slower than tryParse (which parses backwards),
* albeit the latter requires 2 instead of 1 multiplications inside the for(...)
* loop.
*
* Example(s):
*
* With this class, it is possible to write the following code:
*
* int input;
* string inputString;
* do {
* ... any input (e. g. from console) to inputString...
* IntBox result = IntBox.makeIntBox();
* } while ( ! IntBox.tryParse(inputString, result));
* input=result.v(); // an alternative is: input=result.get();
*
* This class itself throws no exceptions. But of course if
* you set an IntBox object to null and later use this object
* a NullPointerException will be thrown.
*
* ********
* To Do: *
* ********
*
* WRITE MORE UNIT TESTS! (see directory src/test/java/utils/casts)
*
* Implement a similar LongBox (should be easy) and DoubleBox class
*
* Port it to pure Java Compiler (JDK) and other IDEs than IntelliJ
*
*
* Created by Peter Sulzer on 2015-07-28.
*
* @author Peter Sulzer
* Copyright (c) 2016, Peter Sulzer, Fürth, Fr, 2016-07-29
*
* @version 1.0, 2015-08-11 (tryParse functions are nearly fully tested
* with unit-tests, a lot of the other functions (mostly very simple)
* have also been already tested with unit tests (using JUnit). Developed
* with JetBrains IntelliJ (Community Edition) version 2016.2.
*
* Developer notes:
*
* I'm not so good with IntelliJ, Gradle, .... Unfortunately the resulting
* name of the *.jar-file
*
* (Menu: IntelliJ-Main-Menü->Build->Build Artifacts...)
*
* is always "casts_main.jar". Rename it to "casts.jar" (manually) and copy
* it to a directory of your classpath (or were it can be found in IntelliJ)
*/