Skip to content

Commit

Permalink
javadocs, javadocs
Browse files Browse the repository at this point in the history
  • Loading branch information
@cowtowncoder
cowtowncoder committed Jan 5, 2021
1 parent e5cbda2 commit aa54f0a
Show file tree
Hide file tree
Showing 5 changed files with 98 additions and 16 deletions.
15 changes: 12 additions & 3 deletions src/main/java/com/fasterxml/jackson/core/base/GeneratorBase.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -434,13 +434,18 @@ public void writeTree(TreeNode rootNode) throws IOException {
*
* @param typeMsg Additional message used for generating exception message
* if value output is NOT legal in current generator output state.
*
* @throws IOException if there is either an underlying I/O problem or encoding
* issue at format layer
*/
protected abstract void _verifyValueWrite(String typeMsg) throws IOException;

/**
* Overridable factory method called to instantiate an appropriate {@link PrettyPrinter}
* for case of "just use the default one", when {@link #useDefaultPrettyPrinter()} is called.
*
* @return Instance of "default" pretty printer to use
*
* @since 2.6
*/
protected PrettyPrinter _constructDefaultPrettyPrinter() {
Expand All @@ -451,6 +456,12 @@ protected PrettyPrinter _constructDefaultPrettyPrinter() {
* Helper method used to serialize a {@link java.math.BigDecimal} as a String,
* for serialization, taking into account configuration settings
*
* @param value BigDecimal value to convert to String
*
* @return String representation of {@code value}
*
* @throws IOException if there is a problem serializing value as String
*
* @since 2.7.7
*/
protected String _asString(BigDecimal value) throws IOException {
Expand All @@ -473,9 +484,7 @@ protected String _asString(BigDecimal value) throws IOException {
/**********************************************************
*/

/**
* @since 2.5
*/
// @since 2.5
protected final int _decodeSurrogate(int surr1, int surr2) throws IOException
{
// First is known to be valid, but how about the other?
Expand Down
41 changes: 37 additions & 4 deletions src/main/java/com/fasterxml/jackson/core/io/NumberInput.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,11 +19,18 @@ public final class NumberInput
final static String MAX_LONG_STR = String.valueOf(Long.MAX_VALUE);

/**
* Fast method for parsing integers that are known to fit into
* Fast method for parsing unsigned integers that are known to fit into
* regular 32-bit signed int type. This means that length is
* between 1 and 9 digits (inclusive)
* between 1 and 9 digits (inclusive) and there is no sign character.
*<p>
* Note: public to let unit tests call it
* Note: public to let unit tests call it; not meant to be used by any
* code outside this package.
*
* @param ch Buffer that contains integer value to decode
* @param off Offset of the first digit character in buffer
* @param len Length of the number to decode (in characters)
*
* @return Decoded {@code int} value
*/
public static int parseInt(char[] ch, int off, int len)
{
Expand Down Expand Up @@ -52,7 +59,16 @@ public static int parseInt(char[] ch, int off, int len)

/**
* Helper method to (more) efficiently parse integer numbers from
* String values.
* String values. Input String must be simple Java integer value.
* No range checks are made to verify that the value fits in 32-bit Java {@code int}:
* caller is expected to only calls this in cases where this can be guaranteed
* (basically: number of digits does not exceed 9)
*<p>
* NOTE: semantics differ significantly from {@link #parseInt(char[], int, int)}.
*
* @param s String that contains integer value to decode
*
* @return Decoded {@code int} value
*/
public static int parseInt(String s)
{
Expand Down Expand Up @@ -115,6 +131,13 @@ public static long parseLong(char[] ch, int off, int len)
return val + (long) parseInt(ch, off+len1, 9);
}

/**
* Similar to {@link #parseInt(String)} but for {@code long} values.
*
* @param s String that contains {@code long} value to decode
*
* @return Decoded {@code long} value
*/
public static long parseLong(String s)
{
// Ok, now; as the very first thing, let's just optimize case of "fake longs";
Expand All @@ -133,8 +156,14 @@ public static long parseLong(String s)
* Note that input String must NOT contain leading minus sign (even
* if 'negative' is set to true).
*
* @param ch Buffer that contains long value to check
* @param off Offset of the first digit character in buffer
* @param len Length of the number to decode (in characters)
* @param negative Whether original number had a minus sign (which is
* NOT passed to this method) or not
*
* @return {@code True} if specified String representation is within Java
* {@code long} range; {@code false} if not.
*/
public static boolean inLongRange(char[] ch, int off, int len,
boolean negative)
Expand All @@ -157,8 +186,12 @@ public static boolean inLongRange(char[] ch, int off, int len,
* Similar to {@link #inLongRange(char[],int,int,boolean)}, but
* with String argument
*
* @param s String that contains {@code long} value to check
* @param negative Whether original number had a minus sign (which is
* NOT passed to this method) or not
*
* @return {@code True} if specified String representation is within Java
* {@code long} range; {@code false} if not.
*/
public static boolean inLongRange(String s, boolean negative)
{
Expand Down
37 changes: 29 additions & 8 deletions src/main/java/com/fasterxml/jackson/core/io/NumberOutput.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,9 +21,8 @@ public final class NumberOutput
private final static int[] TRIPLET_TO_CHARS = new int[1000];

static {
/* Let's fill it with NULLs for ignorable leading digits,
* and digit chars for others
*/
// Let's fill it with NULLs for ignorable leading digits,
// and digit chars for others
int fullIx = 0;
for (int i1 = 0; i1 < 10; ++i1) {
for (int i2 = 0; i2 < 10; ++i2) {
Expand Down Expand Up @@ -51,7 +50,17 @@ public final class NumberOutput
*/

/**
* @return Offset within buffer after outputting int
* Method for appending value of given {@code int} value into
* specified {@code char[]}.
*<p>
* NOTE: caller must guarantee that the output buffer has enough room
* for String representation of the value.
*
* @param v Value to append to buffer
* @param b Buffer to append value to: caller must guarantee there is enough room
* @param off Offset within output buffer ({@code b}) to append number at
*
* @return Offset within buffer after outputting {@code int}
*/
public static int outputInt(int v, char[] b, int off)
{
Expand Down Expand Up @@ -152,7 +161,17 @@ public static int outputInt(int v, byte[] b, int off)
}

/**
* @return Offset within buffer after outputting int
* Method for appending value of given {@code long} value into
* specified {@code char[]}.
*<p>
* NOTE: caller must guarantee that the output buffer has enough room
* for String representation of the value.
*
* @param v Value to append to buffer
* @param b Buffer to append value to: caller must guarantee there is enough room
* @param off Offset within output buffer ({@code b}) to append number at
*
* @return Offset within buffer after outputting {@code long}
*/
public static int outputLong(long v, char[] b, int off)
{
Expand Down Expand Up @@ -258,9 +277,7 @@ public static String toString(double v) {
return Double.toString(v);
}

/**
* @since 2.6.0
*/
// @since 2.6
public static String toString(float v) {
return Float.toString(v);
}
Expand All @@ -275,6 +292,8 @@ public static String toString(float v) {
* Helper method to verify whether given {@code double} value is finite
* (regular rational number} or not (NaN or Infinity).
*
* @param value {@code double} value to check
*
* @return True if number is NOT finite (is Infinity or NaN); false otherwise
*
* Since 2.10
Expand All @@ -288,6 +307,8 @@ public static boolean notFinite(double value) {
* Helper method to verify whether given {@code float} value is finite
* (regular rational number} or not (NaN or Infinity).
*
* @param value {@code float} value to check
*
* @return True if number is NOT finite (is Infinity or NaN); false otherwise
*
* Since 2.10
Expand Down
4 changes: 4 additions & 0 deletions src/main/java/com/fasterxml/jackson/core/io/UTF8Writer.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -354,6 +354,10 @@ public void write(String str, int off, int len) throws IOException
* Method called to calculate Unicode code-point, from a surrogate pair.
*
* @param secondPart Second UTF-16 unit of surrogate (first part stored in {@code _surrogate})
*
* @return Decoded Unicode point
*
* @throws IOException If surrogate pair is invalid
*/
protected int convertSurrogate(int secondPart)
throws IOException
Expand Down
17 changes: 16 additions & 1 deletion src/main/java/com/fasterxml/jackson/core/json/ByteSourceJsonBootstrapper.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -114,6 +114,10 @@ public ByteSourceJsonBootstrapper(IOContext ctxt, byte[] inputBuffer, int inputS
* Method that should be called after constructing an instace.
* It will figure out encoding that content uses, to allow
* for instantiating a proper scanner object.
*
* @return {@link JsonEncoding} detected, if any; {@code JsonEncoding.UTF8} otherwise
*
* @throws IOException If read from underlying input source fails
*/
public JsonEncoding detectEncoding() throws IOException
{
Expand Down Expand Up @@ -178,7 +182,12 @@ public JsonEncoding detectEncoding() throws IOException
/**
* Helper method that may be called to see if given {@link DataInput}
* has BOM marker, and if so, to skip it.
* @throws IOException
*
* @param input DataInput to read content from
*
* @return Byte (as unsigned {@code int}) read after possible UTF-8 BOM
*
* @throws IOException If read from underlying input source fails
*
* @since 2.8
*/
Expand Down Expand Up @@ -272,6 +281,12 @@ public JsonParser constructParser(int parserFeatures, ObjectCodec codec,
* ({@link com.fasterxml.jackson.core.json.ByteSourceJsonBootstrapper});
* supports UTF-8, for example. But it should work, for now, and can
* be improved as necessary.
*
* @param acc InputAccessor to use for accessing content to check
*
* @return Strength of match (never {@code null})
*
* @throws IOException if input access fails due to read problem
*/
public static MatchStrength hasJSONFormat(InputAccessor acc) throws IOException
{
Expand Down

0 comments on commit aa54f0a

Please sign in to comment.