uk.ac.starlink.util

## Class CgiQuery

- java.lang.Object
- - uk.ac.starlink.util.CgiQuery

-     public class CgiQuery
      extends java.lang.Object

  Utility class for constructing CGI query strings. The name is somewhat out of date or misleading; the intention is to provide URLs with a query part that can be interpreted as an application/x-www-form-urlencoded string.
  Since:
    1 Oct 2004

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `QUERY_CHARS` Legal characters for query part of a URI - see RFC 2396.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `CgiQuery(java.lang.String base)` Constructs a CGI query.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `CgiQuery` | `addArgument(java.lang.String name, double value)` Adds a floating point argument to this query.
    `CgiQuery` | `addArgument(java.lang.String name, float value)` Adds a single-precision floating point argument to this query.
    `CgiQuery` | `addArgument(java.lang.String name, long value)` Adds an integer argument to this query.
    `CgiQuery` | `addArgument(java.lang.String name, java.lang.String value)` Adds a string argument to this query.
    `void` | `allowUnencodedChars(java.lang.String extraChars)` Provides a list of characters that will be passed as parameter or value content through without percent-encoding.
    `boolean` | `equals(java.lang.Object o)`
    `static java.lang.String` | `formatDouble(double value)` Formats a double precision value.
    `static java.lang.String` | `formatDouble(double value, int nsf, int maxleng)` Formats a floating point value.
    `static java.lang.String` | `formatFloat(float value)` Formats a single precision value.
    `int` | `hashCode()`
    `java.lang.String` | `toString()` Returns this query as a string.
    `java.net.URL` | `toURL()` Returns this query as a URL.

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### QUERY_CHARS

          public static final java.lang.String QUERY_CHARS

      Legal characters for query part of a URI - see RFC 2396.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### CgiQuery

          public CgiQuery(java.lang.String base)

      Constructs a CGI query. The submitted `base` argument may optionally be a partially-formed CGI-query, that is, one ending in a '?' and zero or more '&name=value' pairs.
      Parameters:
        `base` - base part of the CGI URL
      Throws:
        `java.lang.IllegalArgumentException` - if `base` is not a legal base URL

  - ### Method Detail

    - #### allowUnencodedChars

          public void allowUnencodedChars(java.lang.String extraChars)

      Provides a list of characters that will be passed as parameter or value content through without percent-encoding. The default behaviour is quite conservative, but in many cases this can be relaxed without causing trouble.
      Parameters:
        `extraChars` - string each of whose characters will not be percent-encoded

    - #### addArgument

          public CgiQuery addArgument(java.lang.String name,
                                      long value)

      Adds an integer argument to this query. For convenience the return value is this query.
      Parameters:
        `name` - argument name
        `value` - value for the argument
      Returns:
        this query

    - #### addArgument

          public CgiQuery addArgument(java.lang.String name,
                                      double value)

      Adds a floating point argument to this query. For convenience the return value is this query.
      Parameters:
        `name` - argument name
        `value` - value for the argument
      Returns:
        this query

    - #### addArgument

          public CgiQuery addArgument(java.lang.String name,
                                      float value)

      Adds a single-precision floating point argument to this query. For convenience the return value is this query.
      Parameters:
        `name` - argument name
        `value` - value for the argument
      Returns:
        this query

    - #### addArgument

          public CgiQuery addArgument(java.lang.String name,
                                      java.lang.String value)

      Adds a string argument to this query. For convenience the return value is this query.
      Parameters:
        `name` - argument name
        `value` - unescaped value for the argument
      Returns:
        this query

    - #### toURL

          public java.net.URL toURL()

      Returns this query as a URL.
      Returns:
        query URL

    - #### equals

          public boolean equals(java.lang.Object o)

      Overrides:
        `equals` in class `java.lang.Object`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `java.lang.Object`

    - #### toString

          public java.lang.String toString()

      Returns this query as a string.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        query string

    - #### formatDouble

          public static java.lang.String formatDouble(double value)

      Formats a double precision value.
      Parameters:
        `value` - value
      Returns:
        string representation

    - #### formatFloat

          public static java.lang.String formatFloat(float value)

      Formats a single precision value.
      Parameters:
        `value` - value
      Returns:
        string representation

    - #### formatDouble

          public static java.lang.String formatDouble(double value,
                                                      int nsf,
                                                      int maxleng)

      Formats a floating point value. It will be done in fixed point format if it can be done within the given number of characters, else exponential notation.
      Parameters:
        `value` - value
        `nsf` - number of significant figures
        `maxleng` - maximum length of string - if longer than this, will return to exponential notation
      Returns:
        fixed format string representation