Package org.eclipse.rdf4j.model.util

## Class Literals

- java.lang.Object
- - org.eclipse.rdf4j.model.util.Literals

-     public class Literals
      extends Object

  Various utility methods related to `Literal`.
  Author:
    Arjohn Kampman, Peter Ansell

- - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `Literals()` |

  - ### Method Summary

    All Methods Static Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static boolean` | `canCreateLiteral​(Object object)` | Deprecated. since 3.5.0
    `static Literal` | `createLiteral​(ValueFactory valueFactory, Object object)` | Deprecated. since 3.5.0 - use `Values.literal(Object)` instead.
    `static Literal` | `createLiteralOrFail​(ValueFactory valueFactory, Object object)` | Deprecated. since 3.5.0 - use `Values.literal(Object, boolean)` instead.
    `static boolean` | `getBooleanValue​(Literal l, boolean fallback)` | Gets the boolean value of the supplied literal.
    `static boolean` | `getBooleanValue​(Value v, boolean fallback)` | Returns the result of `getBooleanValue((Literal)value, fallback)` in case the supplied value is a literal, returns the fallback value otherwise.
    `static byte` | `getByteValue​(Literal l, byte fallback)` | Gets the byte value of the supplied literal.
    `static byte` | `getByteValue​(Value v, byte fallback)` | Returns the result of `getByteValue((Literal)value, fallback)` in case the supplied value is a literal, returns the fallback value otherwise.
    `static XMLGregorianCalendar` | `getCalendarValue​(Literal l, XMLGregorianCalendar fallback)` | Gets the calendar value of the supplied literal.
    `static XMLGregorianCalendar` | `getCalendarValue​(Value v, XMLGregorianCalendar fallback)` | Returns the result of `getCalendarValue((Literal)value, fallback)` in case the supplied value is a literal, returns the fallback value otherwise.
    `static BigDecimal` | `getDecimalValue​(Literal l, BigDecimal fallback)` | Gets the decimal value of the supplied literal.
    `static BigDecimal` | `getDecimalValue​(Value v, BigDecimal fallback)` | Returns the result of `getDecimalValue((Literal)value, fallback)` in case the supplied value is a literal, returns the fallback value otherwise.
    `static double` | `getDoubleValue​(Literal l, double fallback)` | Gets the double value of the supplied literal.
    `static double` | `getDoubleValue​(Value v, double fallback)` | Returns the result of `getDoubleValue((Literal)value, fallback)` in case the supplied value is a literal, returns the fallback value otherwise.
    `static Duration` | `getDurationValue​(Literal l, Duration fallback)` | Gets the `Duration` value of the supplied literal.
    `static float` | `getFloatValue​(Literal l, float fallback)` | Gets the float value of the supplied literal.
    `static float` | `getFloatValue​(Value v, float fallback)` | Returns the result of `getFloatValue((Literal)value, fallback)` in case the supplied value is a literal, returns the fallback value otherwise.
    `static BigInteger` | `getIntegerValue​(Literal l, BigInteger fallback)` | Gets the integer value of the supplied literal.
    `static BigInteger` | `getIntegerValue​(Value v, BigInteger fallback)` | Returns the result of `getIntegerValue((Literal)value, fallback)` in case the supplied value is a literal, returns the fallback value otherwise.
    `static int` | `getIntValue​(Literal l, int fallback)` | Gets the int value of the supplied literal.
    `static int` | `getIntValue​(Value v, int fallback)` | Returns the result of `getIntValue((Literal)value, fallback)` in case the supplied value is a literal, returns the fallback value otherwise.
    `static String` | `getLabel​(Optional<Value> v, String fallback)` |
    `static String` | `getLabel​(Literal l, String fallback)` | Gets the label of the supplied literal.
    `static String` | `getLabel​(Value v, String fallback)` | Returns the result of `getLabel((Literal)v, fallback` in case the supplied value is a literal, returns the fallback value otherwise.
    `static long` | `getLongValue​(Literal l, long fallback)` | Gets the long value of the supplied literal.
    `static long` | `getLongValue​(Value v, long fallback)` | Returns the result of `getLongValue((Literal)value, fallback)` in case the supplied value is a literal, returns the fallback value otherwise.
    `static short` | `getShortValue​(Literal l, short fallback)` | Gets the short value of the supplied literal.
    `static short` | `getShortValue​(Value v, short fallback)` | Returns the result of `getShortValue((Literal)value, fallback)` in case the supplied value is a literal, returns the fallback value otherwise.
    `static Optional<XSD.Datatype>` | `getXsdDatatype​(Literal l)` | Deprecated, for removal: This API element is subject to removal in a future version. Use `Literal.getCoreDatatype()` instead.
    `static boolean` | `isLanguageLiteral​(Literal literal)` | Helper method to determine whether a literal is a language literal, and not a typed literal.
    `static boolean` | `isValidLanguageTag​(String languageTag)` | Checks if the given string is a well-formed BCP47 language tag according to the rules defined in RFC 5646, section 2.1.1.
    `static boolean` | `langMatches​(String langTag, String langRange)` | Implements language range filtering for SPARQL langMatches (https://www.w3.org/TR/sparql11-query/#func-langMatches).
    `static String` | `normalizeLanguageTag​(String languageTag)` | Normalizes the given BCP47 language tag according to the rules defined in RFC 5646, section 2.1.1:

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

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### Literals

          protected Literals()

  - ### Method Detail

    - #### getLabel

          public static String getLabel​(Literal l,
                                        String fallback)

      Gets the label of the supplied literal. The fallback value is returned in case the supplied literal is null.
      Parameters:
        `l` - The literal to get the label for.
        `fallback` - The value to fall back to in case the supplied literal is null.
      Returns:
        Either the literal's label, or the fallback value.

    - #### getLabel

          public static String getLabel​(Value v,
                                        String fallback)

      Returns the result of `getLabel((Literal)v, fallback` in case the supplied value is a literal, returns the fallback value otherwise.

    - #### getLabel

          public static String getLabel​(Optional<Value> v,
                                        String fallback)

    - #### getXsdDatatype

          @Deprecated(since="4.0.0",
                      forRemoval=true)
          public static Optional<XSD.Datatype> getXsdDatatype​(Literal l)

      Deprecated, for removal: This API element is subject to removal in a future version.
      Use `Literal.getCoreDatatype()` instead.
      Retrieves the `XSD.Datatype` value for the supplied Literal, if it has one.
      Parameters:
        `l` - a Literal
      Returns:
        an Optional `XSD.Datatype` enum, if one is available. Note that the absence of this enum does not indicate that the literal has no datatype, merely that it has no cached enum representation of that datatype.
      Since:
        3.5.0

    - #### getByteValue

          public static byte getByteValue​(Literal l,
                                          byte fallback)

      Gets the byte value of the supplied literal. The fallback value is returned in case `Literal.byteValue()` throws a `NumberFormatException`.
      Parameters:
        `l` - The literal to get the byte value for.
        `fallback` - The value to fall back to in case no byte value could gotten from the literal.
      Returns:
        Either the literal's byte value, or the fallback value.

    - #### getByteValue

          public static byte getByteValue​(Value v,
                                          byte fallback)

      Returns the result of `getByteValue((Literal)value, fallback)` in case the supplied value is a literal, returns the fallback value otherwise.

    - #### getShortValue

          public static short getShortValue​(Literal l,
                                            short fallback)

      Gets the short value of the supplied literal. The fallback value is returned in case `Literal.shortValue()` throws a `NumberFormatException`.
      Parameters:
        `l` - The literal to get the short value for.
        `fallback` - The value to fall back to in case no short value could gotten from the literal.
      Returns:
        Either the literal's short value, or the fallback value.

    - #### getShortValue

          public static short getShortValue​(Value v,
                                            short fallback)

      Returns the result of `getShortValue((Literal)value, fallback)` in case the supplied value is a literal, returns the fallback value otherwise.

    - #### getIntValue

          public static int getIntValue​(Literal l,
                                        int fallback)

      Gets the int value of the supplied literal. The fallback value is returned in case `Literal.intValue()` throws a `NumberFormatException`.
      Parameters:
        `l` - The literal to get the int value for.
        `fallback` - The value to fall back to in case no int value could gotten from the literal.
      Returns:
        Either the literal's int value, or the fallback value.

    - #### getIntValue

          public static int getIntValue​(Value v,
                                        int fallback)

      Returns the result of `getIntValue((Literal)value, fallback)` in case the supplied value is a literal, returns the fallback value otherwise.

    - #### getLongValue

          public static long getLongValue​(Literal l,
                                          long fallback)

      Gets the long value of the supplied literal. The fallback value is returned in case `Literal.longValue()` throws a `NumberFormatException`.
      Parameters:
        `l` - The literal to get the long value for.
        `fallback` - The value to fall back to in case no long value could gotten from the literal.
      Returns:
        Either the literal's long value, or the fallback value.

    - #### getLongValue

          public static long getLongValue​(Value v,
                                          long fallback)

      Returns the result of `getLongValue((Literal)value, fallback)` in case the supplied value is a literal, returns the fallback value otherwise.

    - #### getIntegerValue

          public static BigInteger getIntegerValue​(Literal l,
                                                   BigInteger fallback)

      Gets the integer value of the supplied literal. The fallback value is returned in case `Literal.integerValue()` throws a `NumberFormatException`.
      Parameters:
        `l` - The literal to get the integer value for.
        `fallback` - The value to fall back to in case no integer value could gotten from the literal.
      Returns:
        Either the literal's integer value, or the fallback value.

    - #### getIntegerValue

          public static BigInteger getIntegerValue​(Value v,
                                                   BigInteger fallback)

      Returns the result of `getIntegerValue((Literal)value, fallback)` in case the supplied value is a literal, returns the fallback value otherwise.

    - #### getDecimalValue

          public static BigDecimal getDecimalValue​(Literal l,
                                                   BigDecimal fallback)

      Gets the decimal value of the supplied literal. The fallback value is returned in case `Literal.decimalValue()` throws a `NumberFormatException`.
      Parameters:
        `l` - The literal to get the decimal value for.
        `fallback` - The value to fall back to in case no decimal value could gotten from the literal.
      Returns:
        Either the literal's decimal value, or the fallback value.

    - #### getDecimalValue

          public static BigDecimal getDecimalValue​(Value v,
                                                   BigDecimal fallback)

      Returns the result of `getDecimalValue((Literal)value, fallback)` in case the supplied value is a literal, returns the fallback value otherwise.

    - #### getFloatValue

          public static float getFloatValue​(Literal l,
                                            float fallback)

      Gets the float value of the supplied literal. The fallback value is returned in case `Literal.floatValue()` throws a `NumberFormatException`.
      Parameters:
        `l` - The literal to get the float value for.
        `fallback` - The value to fall back to in case no float value could gotten from the literal.
      Returns:
        Either the literal's float value, or the fallback value.

    - #### getFloatValue

          public static float getFloatValue​(Value v,
                                            float fallback)

      Returns the result of `getFloatValue((Literal)value, fallback)` in case the supplied value is a literal, returns the fallback value otherwise.

    - #### getDoubleValue

          public static double getDoubleValue​(Literal l,
                                              double fallback)

      Gets the double value of the supplied literal. The fallback value is returned in case `Literal.doubleValue()` throws a `NumberFormatException`.
      Parameters:
        `l` - The literal to get the double value for.
        `fallback` - The value to fall back to in case no double value could gotten from the literal.
      Returns:
        Either the literal's double value, or the fallback value.

    - #### getDoubleValue

          public static double getDoubleValue​(Value v,
                                              double fallback)

      Returns the result of `getDoubleValue((Literal)value, fallback)` in case the supplied value is a literal, returns the fallback value otherwise.

    - #### getBooleanValue

          public static boolean getBooleanValue​(Literal l,
                                                boolean fallback)

      Gets the boolean value of the supplied literal. The fallback value is returned in case `Literal.booleanValue()` throws a `NumberFormatException`.
      Parameters:
        `l` - The literal to get the boolean value for.
        `fallback` - The value to fall back to in case no boolean value could gotten from the literal.
      Returns:
        Either the literal's boolean value, or the fallback value.

    - #### getBooleanValue

          public static boolean getBooleanValue​(Value v,
                                                boolean fallback)

      Returns the result of `getBooleanValue((Literal)value, fallback)` in case the supplied value is a literal, returns the fallback value otherwise.

    - #### getCalendarValue

          public static XMLGregorianCalendar getCalendarValue​(Literal l,
                                                              XMLGregorianCalendar fallback)

      Gets the calendar value of the supplied literal. The fallback value is returned in case `Literal.calendarValue()` throws a `NumberFormatException`.
      Parameters:
        `l` - The literal to get the calendar value for.
        `fallback` - The value to fall back to in case no calendar value could gotten from the literal.
      Returns:
        Either the literal's calendar value, or the fallback value.

    - #### getDurationValue

          public static Duration getDurationValue​(Literal l,
                                                  Duration fallback)

      Gets the `Duration` value of the supplied literal. The fallback value is returned in case `XMLDatatypeUtil.parseDuration(String)` throws an exception.
      Parameters:
        `l` - The literal to get the `Duration` value for.
        `fallback` - The value to fall back to in case no Duration value could gotten from the literal.
      Returns:
        Either the literal's Duration value, or the fallback value.

    - #### getCalendarValue

          public static XMLGregorianCalendar getCalendarValue​(Value v,
                                                              XMLGregorianCalendar fallback)

      Returns the result of `getCalendarValue((Literal)value, fallback)` in case the supplied value is a literal, returns the fallback value otherwise.

    - #### createLiteral

          @Deprecated
          public static Literal createLiteral​(ValueFactory valueFactory,
                                              Object object)

      Deprecated.
      since 3.5.0 - use `Values.literal(Object)` instead.
      Creates a typed `Literal` out of the supplied object, mapping the runtime type of the object to the appropriate XML Schema type. If no mapping is available, the method returns a literal with the string representation of the supplied object as the value, and `XSD.STRING` as the datatype. Recognized types are `Boolean`, `Byte`, `Double`, `Float`, `Integer`, `Long`, `Short`, `XMLGregorianCalendar` , and `Date`.
      Parameters:
        `valueFactory` -
        `object` - an object to be converted to a typed literal.
      Returns:
        a typed literal representation of the supplied object.
      Throws:
        `NullPointerException` - If the object was null.

    - #### createLiteralOrFail

          @Deprecated
          public static Literal createLiteralOrFail​(ValueFactory valueFactory,
                                                    Object object)
                                             throws LiteralUtilException

      Deprecated.
      since 3.5.0 - use `Values.literal(Object, boolean)` instead.
      Creates a typed `Literal` out of the supplied object, mapping the runtime type of the object to the appropriate XML Schema type. If no mapping is available, the method throws a `LiteralUtilException`. Recognized types are `Boolean`, `Byte`, `Double`, `Float`, `Integer`, `Long`, `Short`, `XMLGregorianCalendar` , and `Date`.
      Parameters:
        `valueFactory` -
        `object` - an object to be converted to a typed literal.
      Returns:
        a typed literal representation of the supplied object.
      Throws:
        `LiteralUtilException` - If the literal could not be created.
        `NullPointerException` - If the object was null.

    - #### canCreateLiteral

          @Deprecated
          public static boolean canCreateLiteral​(Object object)

      Deprecated.
      since 3.5.0
      Helper method for determining whether a literal could be created from an object using a `ValueFactory`.
      Parameters:
        `object` - an object to check for the possibility of being converted to a typed literal.
      Returns:
        True if a literal could be created from the given object, based solely on its type and the methods available on the `ValueFactory` interface and false otherwise. Returns false if the object is null.

    - #### isLanguageLiteral

          public static boolean isLanguageLiteral​(Literal literal)

      Helper method to determine whether a literal is a language literal, and not a typed literal.
      Parameters:
        `literal` - The literal to check
      Returns:
        True if the literal has a language tag attached to it and false otherwise.

    - #### normalizeLanguageTag

          public static String normalizeLanguageTag​(String languageTag)
                                             throws IllformedLocaleException

      Normalizes the given BCP47 language tag according to the rules defined in RFC 5646, section 2.1.1:

      > All subtags, including extension and private use subtags, use lowercase letters with two exceptions: two-letter and four-letter subtags that neither appear at the start of the tag nor occur after singletons. Such two-letter subtags are all uppercase (as in the tags "en-CA-x-ca" or "sgn-BE-FR") and four- letter subtags are titlecase (as in the tag "az-Latn-x-latn").

      Parameters:
        `languageTag` - An unnormalized, valid, language tag
      Returns:
        A normalized version of the given language tag
      Throws:
        `IllformedLocaleException` - If the given language tag is ill-formed according to the rules specified in BCP47 (RFC 5646).

    - #### isValidLanguageTag

          public static boolean isValidLanguageTag​(String languageTag)

      Checks if the given string is a well-formed BCP47 language tag according to the rules defined in RFC 5646, section 2.1.1.
      Parameters:
        `languageTag` - A language tag
      Returns:
        `true` if the given language tag is well-formed according to the rules specified in BCP47.

    - #### langMatches

          public static boolean langMatches​(String langTag,
                                            String langRange)

      Implements language range filtering for SPARQL langMatches (https://www.w3.org/TR/sparql11-query/#func-langMatches).
      Parameters:
        `langTag` - the tag to filter
        `langRange` - the range to filter against
      Returns:
        true if langTag matches langRange