rdf 3.2.3 → 3.2.6

data/lib/rdf/model/literal/integer.rb

@@ -78,7 +78,10 @@ module RDF; class Literal
     ##
     # Returns the absolute value of `self`.
     #
+    # From the XQuery function [fn:abs](https://www.w3.org/TR/xpath-functions/#func-abs).
+    #
     # @return [RDF::Literal]
+    # @see https://www.w3.org/TR/xpath-functions/#func-abs
     # @since  0.2.3
     def abs
       (n = to_i) && n > 0 ? self : self.class.new(n.abs)
@@ -87,7 +90,10 @@ module RDF; class Literal
     ##
     # Returns `self`.
     #
+    # From the XQuery function [fn:round](https://www.w3.org/TR/xpath-functions/#func-round).
+    #
     # @return [RDF::Literal]
+    # @see https://www.w3.org/TR/xpath-functions/#func-round
     def round
       self
     end

data/lib/rdf/model/literal/numeric.rb

@@ -67,10 +67,9 @@ module RDF; class Literal
     ##
     # Returns the sum of `self` plus `other`.
     #
-    # For xs:float or xs:double values, if one of the operands is a zero or a finite number
-    # and the other is INF or -INF, INF or -INF is returned. If both operands are INF, INF is returned.
-    # If both operands are -INF, -INF is returned. If one of the operands is INF
-    # and the other is -INF, NaN is returned.
+    # From the XQuery function [op:numeric-add](https://www.w3.org/TR/xpath-functions/#func-numeric-add).
+    #
+    # @note For `xs:float` or `xs:double` values, if one of the operands is a zero or a finite number and the other is `INF` or `-INF`, `INF` or `-INF` is returned. If both operands are `INF`, `INF` is returned. If both operands are `-INF`, `-INF` is returned. If one of the operands is `INF` and the other is `-INF`, `NaN` is returned.
     # @param  [Literal::Numeric, #to_i, #to_f, #to_d] other
     # @return [RDF::Literal::Numeric]
     # @since  0.2.3
@@ -90,6 +89,8 @@ module RDF; class Literal
     ##
     # Returns the difference of `self` minus `other`.
     #
+    # From the XQuery function [op:numeric-subtract](https://www.w3.org/TR/xpath-functions/#func-numeric-subtract).
+    #
     # @param  [Literal::Numeric, #to_i, #to_f, #to_d] other
     # @return [RDF::Literal::Numeric]
     # @since  0.2.3
@@ -109,6 +110,8 @@ module RDF; class Literal
     ##
     # Returns the product of `self` times `other`.
     #
+    # From the XQuery function [op:numeric-multiply](https://www.w3.org/TR/xpath-functions/#func-numeric-multiply).
+    #
     # @param  [Literal::Numeric, #to_i, #to_f, #to_d] other
     # @return [RDF::Literal::Numeric]
     # @since  0.2.3
@@ -130,6 +133,8 @@ module RDF; class Literal
     #
     # Promotes values, as necessary, with the result type depending on the input values.
     #
+    # From the XQuery function [math:pow](https://www.w3.org/TR/xpath-functions/#func-numeric-pow).
+    #
     # @param  [Literal::Numeric, #to_i, #to_f, #to_d] other
     # @return [RDF::Literal::Numeric]
     # @since  0.2.3
@@ -143,6 +148,8 @@ module RDF; class Literal
     ##
     # Exponent − Performs remainder of `self` divided by `other`.
     #
+    # From the XQuery function [math:mod](https://www.w3.org/TR/xpath-functions/#func-numeric-mod).
+    #
     # @param  [Literal::Numeric, #to_i, #to_f, #to_d] other
     # @return [RDF::Literal]
     # @since  0.2.3
@@ -165,6 +172,8 @@ module RDF; class Literal
     # As a special case, if the types of both $arg1 and $arg2 are xsd:integer,
     # then the return type is xsd:decimal.
     #
+    # From the XQuery function [op:numeric-divide](https://www.w3.org/TR/xpath-functions/#func-numeric-divide).
+    #
     # @param  [Literal::Numeric, #to_i, #to_f, #to_d] other
     # @return [RDF::Literal::Numeric]
     # @raise  [ZeroDivisionError] if divided by zero
@@ -183,8 +192,11 @@ module RDF; class Literal
     ##
     # Returns the absolute value of `self`.
     #
+    # From the XQuery function [fn:abs](https://www.w3.org/TR/xpath-functions/#func-abs).
+    #
     # @return [RDF::Literal]
     # @raise  [NotImplementedError] unless implemented in subclass
+    # @see https://www.w3.org/TR/xpath-functions/#func-abs
     def abs
       raise NotImplementedError
     end
@@ -192,8 +204,11 @@ module RDF; class Literal
     ##
     # Returns the number with no fractional part that is closest to the argument. If there are two such numbers, then the one that is closest to positive infinity is returned. An error is raised if arg is not a numeric value.
     #
+    # From the XQuery function [fn:round](https://www.w3.org/TR/xpath-functions/#func-round).
+    #
     # @return [RDF::Literal]
     # @raise  [NotImplementedError] unless implemented in subclass
+    # @see https://www.w3.org/TR/xpath-functions/#func-round
     def round
       raise NotImplementedError
     end
@@ -201,10 +216,13 @@ module RDF; class Literal
     ##
     # Returns the smallest integer greater than or equal to `self`.
     #
+    # From the XQuery function [fn:ceil](https://www.w3.org/TR/xpath-functions/#func-ceil).
+    #
     # @example
     #   RDF::Literal(1).ceil            #=> RDF::Literal(1)
     #
     # @return [RDF::Literal]
+    # @see https://www.w3.org/TR/xpath-functions/#func-ceil
     def ceil
       self
     end
@@ -212,14 +230,146 @@ module RDF; class Literal
     ##
     # Returns the largest integer less than or equal to `self`.
     #
+    # From the XQuery function [fn:floor](https://www.w3.org/TR/xpath-functions/#func-floor).
+    #
     # @example
     #   RDF::Literal(1).floor            #=> RDF::Literal(1)
     #
     # @return [RDF::Literal]
+    # @see https://www.w3.org/TR/xpath-functions/#func-floor
     def floor
       self
     end
 
+    ##
+    # Returns the value of `e`<sup>`x`</sup>.
+    #
+    # @return [Double]
+    # @see https://www.w3.org/TR/xpath-functions/#func-math-exp
+    def exp
+      Double.new(Math.exp(self.to_f))
+    end
+
+    ##
+    # Returns the value of `10`<sup>`x`</sup>.
+    #
+    # @return [Double]
+    # @see https://www.w3.org/TR/xpath-functions/#func-math-exp10
+    def exp10
+      Double.new(10**self.to_f)
+    end
+
+    ##
+    # Returns the natural logarithm of the argument.
+    #
+    # @return [Double]
+    # @see https://www.w3.org/TR/xpath-functions/#func-math-log
+    def log
+      Double.new(Math.log(self.to_f))
+    rescue Math::DomainError
+      Double.new(::Float::NAN)
+    end
+
+    ##
+    # Returns the base-ten logarithm of the argument.
+    #
+    # @return [Double]
+    # @see https://www.w3.org/TR/xpath-functions/#func-math-log10
+    def log10
+      Double.new(Math.log10(self.to_f))
+    rescue Math::DomainError
+      Double.new(::Float::NAN)
+    end
+
+    ##
+    # Returns the non-negative square root of the argument.
+    #
+    # @return [Double]
+    # @see https://www.w3.org/TR/xpath-functions/#func-math-sqrt
+    def sqrt
+      Double.new(Math.sqrt(self.to_f))
+    rescue Math::DomainError
+      Double.new(::Float::NAN)
+    end
+
+    ##
+    # Returns the sine of the argument. The argument is an angle in radians.
+    #
+    # @return [Double]
+    # @see https://www.w3.org/TR/xpath-functions/#func-math-sin
+    def sin
+      Double.new(Math.sin(self.to_f))
+    rescue Math::DomainError
+      Double.new(::Float::NAN)
+    end
+
+    ##
+    # Returns the cosine of the argument. The argument is an angle in radians.
+    #
+    # @return [Double]
+    # @see https://www.w3.org/TR/xpath-functions/#func-math-cos
+    def cos
+      Double.new(Math.cos(self.to_f))
+    rescue Math::DomainError
+      Double.new(::Float::NAN)
+    end
+
+    ##
+    # Returns the tangent of the argument. The argument is an angle in radians.
+    #
+    # @return [Double]
+    # @see https://www.w3.org/TR/xpath-functions/#func-math-tan
+    def tan
+      Double.new(Math.tan(self.to_f))
+    rescue Math::DomainError
+      Double.new(::Float::NAN)
+    end
+
+    ##
+    # Returns the arc sine of the argument.
+    #
+    # @return [Double]
+    # @see https://www.w3.org/TR/xpath-functions/#func-math-asin
+    def asin
+      Double.new(Math.asin(self.to_f))
+    rescue Math::DomainError
+      Double.new(::Float::NAN)
+    end
+
+    ##
+    # Returns the arc cosine of the argument.
+    #
+    # @return [Double]
+    # @see https://www.w3.org/TR/xpath-functions/#func-math-acos
+    def acos
+      Double.new(Math.acos(self.to_f))
+    rescue Math::DomainError
+      Double.new(::Float::NAN)
+    end
+
+    ##
+    # Returns the arc tangent of the argument.
+    #
+    # @return [Double]
+    # @see https://www.w3.org/TR/xpath-functions/#func-math-atan
+    def atan
+      Double.new(Math.atan(self.to_f))
+    rescue Math::DomainError
+      Double.new(::Float::NAN)
+    end
+
+    ##
+    # Returns the angle in radians subtended at the origin by the point on a plane with coordinates (x, y) and the positive x-axis.
+    #
+    # @param [#to_f] arg
+    # @return [Double]
+    # @see https://www.w3.org/TR/xpath-functions/#func-math-atan2
+    def atan2(arg)
+      Double.new(Math.atan2(self.to_f, arg.to_f))
+    rescue Math::DomainError
+      Double.new(::Float::NAN)
+    end
+
     ##
     # Returns the value as an integer.
     #

data/lib/rdf/model/literal/temporal.rb

@@ -0,0 +1,310 @@
+module RDF; class Literal
+  ##
+  # Shared methods and class ancestry for date, time, and dateTime literal classes.
+  #
+  # @since 3.1
+  class Temporal < Literal
+    # Matches either -10:00 or -P1H0M forms
+    ZONE_GRAMMAR  = %r(\A
+       (?:(?<si>[+-])(?<hr>\d{2}):(?:(?<mi>\d{2}))?)
+      |(?:(?<si>-)?PT(?<hr>\d{1,2})H(?:(?<mi>\d{1,2})M)?)
+    \z)x.freeze
+
+    ##
+    # Compares this literal to `other` for sorting purposes.
+    #
+    # @param  [Object] other
+    # @return [Integer] `-1`, `0`, or `1`
+    def <=>(other)
+      # If lexically invalid, use regular literal testing
+      return super unless self.valid? && (!other.respond_to?(:valid?) || other.valid?)
+      return super unless other.is_a?(self.class)
+      @object <=> other.object
+    end
+
+    ##
+    # Returns `true` if this literal is equal to `other`.
+    #
+    # @param  [Object] other
+    # @return [Boolean] `true` or `false`
+    # @since  0.3.0
+    def ==(other)
+      # If lexically invalid, use regular literal testing
+      return super unless self.valid? && (!other.respond_to?(:valid?) || other.valid?)
+
+      case other
+      when self.class
+        self.object == other.object
+      when Literal::Temporal
+        false
+      else
+        super
+      end
+    end
+
+    ##
+    # Converts this literal into its canonical lexical representation.
+    # with date and time normalized to UTC.
+    #
+    # @return [RDF::Literal] `self`
+    # @see    http://www.w3.org/TR/xmlschema11-2/#dateTime
+    def canonicalize!
+      if self.valid? && @zone && @zone != '+00:00'
+        adjust_to_timezone!
+      else
+        @string = nil
+      end
+      self
+    end
+
+    ##
+    # Returns the timezone part of arg as a simple literal. Returns the empty string if there is no timezone.
+    #
+    # @return [RDF::Literal]
+    def tz
+      RDF::Literal(@zone == "+00:00" ? 'Z' : @zone)
+    end
+
+    ##
+    # Does the literal representation include a timezone? Note that this is only possible if initialized using a string, or `:lexical` option.
+    #
+    # @return [Boolean]
+    # @since 1.1.6
+    def timezone?
+      # Can only know there's a timezone from the string represntation
+      md = to_s.match(self.class.const_get(:GRAMMAR))
+      md && !!md[2]
+    end
+    alias_method :tz?, :timezone?
+    alias_method :has_tz?, :timezone?
+    alias_method :has_timezone?, :timezone?
+
+    ##
+    # Returns the timezone part of arg as an xsd:dayTimeDuration, or `nil`
+    # if lexical form of literal does not include a timezone.
+    #
+    # From [fn:timezone-from-date](https://www.w3.org/TR/xpath-functions/#func-timezone-from-date).
+    #
+    # @return [RDF::Literal]
+    # @see https://www.w3.org/TR/xpath-functions/#func-timezone-from-date
+    def timezone
+      if @zone
+        md = @zone.match(ZONE_GRAMMAR)
+        si, hr, mi = md[:si], md[:hr].to_i, md[:mi].to_i
+        si = nil unless si == "-"
+        res = "#{si}PT#{hr}H#{"#{mi}M" if mi > 0}"
+        RDF::Literal(res, datatype: RDF::URI("http://www.w3.org/2001/XMLSchema#dayTimeDuration"))
+      end
+    end
+
+    ##
+    # Returns `true` if the value adheres to the defined grammar of the
+    # datatype.
+    #
+    # Special case for date and dateTime, for which '0000' is not a valid year
+    #
+    # @return [Boolean]
+    # @since  0.2.1
+    def valid?
+      super && object && value !~ %r(\A0000)
+    end
+
+    ##
+    # Does the literal representation include millisectonds?
+    #
+    # @return [Boolean]
+    # @since 1.1.6
+    def milliseconds?
+      object.strftime("%L").to_i > 0
+    end
+    alias_method :has_milliseconds?, :milliseconds?
+    alias_method :has_ms?, :milliseconds?
+    alias_method :ms?, :milliseconds?
+
+    ##
+    # Returns the `timezone` of the literal. If the
+    ##
+    # Returns the value as a string.
+    #
+    # @return [String]
+    def to_s
+      @string ||= (@object.strftime(self.class.const_get(:FORMAT)).sub('.000', '') + self.tz)
+    end
+
+    ##
+    # Adjust the timezone.
+    #
+    # From [fn:adjust-dateTime-to-timezone](https://www.w3.org/TR/xpath-functions/#func-adjust-dateTime-to-timezone)
+    #
+    # @overload adjust_to_timezone!
+    #   Adjusts the timezone to UTC.
+    #
+    #   @return [Temporal] `self`
+    #   @raise [RangeError] if `zone < -14*60` or `zone > 14*60`
+    # @overload adjust_to_timezone!(zone)
+    #   If `zone` is nil, then the timzeone component is removed.
+    #
+    #   Otherwise, the timezone is set based on the difference between the current timezone offset (if any) and `zone`.
+    #
+    #   @param [DayTimeDuration, String] zone (nil) In the form of {ZONE_GRAMMAR}.
+    #   @return [Temporal] `self`
+    #   @raise [RangeError] if `zone < -14*60` or `zone > 14*60`
+    # @see https://www.w3.org/TR/xpath-functions/#func-adjust-dateTime-to-timezone
+    def adjust_to_timezone!(*args)
+      zone = args.empty? ? '+00:00' : args.first
+      if zone.to_s.empty?
+        # Remove timezone component
+        @object = self.class.new(@object.strftime(self.class.const_get(:FORMAT))).object
+        @zone = nil
+      else
+        md = zone.to_s.match(ZONE_GRAMMAR)
+        raise ArgumentError,
+              "expected #{zone.inspect} to be a xsd:dayTimeDuration or +/-HH:MM" unless md
+
+        # Adjust to zone
+        si, hr, mi = md[:si], md[:hr], md[:mi]
+        si ||= '+'
+        offset = hr.to_i * 60 + mi.to_i
+        raise ArgumentError,
+              "Zone adjustment of #{zone} out of range" if
+              md.nil? || offset > 14*60
+
+        new_zone = "%s%.2d:%.2d" % [si, hr.to_i, mi.to_i]
+        dt = @zone.nil? ? @object : @object.new_offset(new_zone)
+        @object = self.class.new(dt.strftime(self.class.const_get(:FORMAT) + new_zone)).object
+        @zone = new_zone
+      end
+      @string = nil
+      self
+    end
+
+    ##
+    # Functional version of `#adjust_to_timezone!`.
+    #
+    # @overload adjust_to_timezone
+    #   @param (see #adjust_to_timezone!)
+    #   @return [DateTime]
+    #   @raise (see #adjust_to_timezone!)
+    # @overload adjust_to_timezone(zone) (see #adjust_to_timezone!)
+    #   @return [DateTime]
+    #   @raise (see #adjust_to_timezone!)
+    def adjust_to_timezone(*args)
+      self.dup.adjust_to_timezone!(*args)
+    end
+
+    ##
+    # Add a Duration to a Temporal.
+    #
+    # For YearMonthDuration, turns duration into months and adds to internal DateTime object.
+    #
+    # For DayTimeDuration, turns duration into rational days, and adds to internal DateTime object.
+    #
+    # @note This depends on the parameter responding to `#to_i` or `#to_r`, which for Duration types, is implemented in the rdf-xsd gem.
+    #
+    # @param [YearMonthDuration, DayTimeDuration] other
+    # @return [Temporal]
+    # @see https://www.w3.org/TR/xpath-functions/#func-add-yearMonthDuration-to-dateTime
+    # @see https://www.w3.org/TR/xpath-functions/#func-add-dayTimeDuration-to-dateTime
+    def +(other)
+      new_dt = case other
+      when YearMonthDuration
+        @object >> other.to_i
+      when DayTimeDuration
+        @object + other.to_r
+      else
+        return super
+      end
+
+      dt = new_dt.strftime(self.class.const_get(:FORMAT)) + tz
+      self.class.new(dt)
+    rescue NoMethodError => e
+      raise "Consider including the rdf-xsd class for method implementaions: #{e.message}"
+    end
+
+    ##
+    # Subtract times or durations from a temporal.
+    #
+    # @overload +(other)
+    #   For YearMonthDuration, turns duration into months and subtracts from internal DateTime object resulting in a new {Temporal} object.
+    #
+    #   For DayTimeDuration, turns duration into rational days, and subtracts from internal DateTime object resulting in a new {Temporal} object.
+    #
+    #   For Temporal, subtracts the two moments resulting in a `xsd:dayTimeDuration`.
+    #
+    #   @param [YearMonthDuration, DayTimeDurationm, Temporal] other
+    #   @return [Temporal, DayTimeDuration]
+    #   @note This depends on the parameter responding to `#to_i` or `#to_r`, which for Duration types, is implemented in the rdf-xsd gem.
+    #   @see https://www.w3.org/TR/xpath-functions/#func-subtract-yearMonthDuration-from-dateTime
+    #   @see https://www.w3.org/TR/xpath-functions/#func-subtract-dayTimeDuration-from-dateTime
+    #   @see https://www.w3.org/TR/xpath-functions/#func-subtract-dateTimes
+    def -(other)
+      new_dt = case other
+      when YearMonthDuration
+        @object << other.to_i
+      when DayTimeDuration
+        @object - other.to_r
+      when Temporal
+        @object - other.object
+      else
+        return super
+      end
+
+      if new_dt.is_a?(Rational)
+        RDF::Literal(new_dt, datatype: RDF::XSD.dayTimeDuration)
+      else
+        dt = new_dt.strftime(self.class.const_get(:FORMAT)) + tz
+        self.class.new(dt)
+      end
+    rescue NoMethodError => e
+      raise "Consider including the rdf-xsd class for method implementaions: #{e.message}"
+    end
+
+    # Years
+    #
+    # From the XQuery function [fn:year-from-dateTime](https://www.w3.org/TR/xpath-functions/#func-year-from-dateTime).
+    #
+    # @return [Integer]
+    # @see https://www.w3.org/TR/xpath-functions/#func-year-from-dateTime
+    def year; Integer.new(object.year); end
+
+    # Months
+    #
+    # From the XQuery function [fn:month-from-dateTime](https://www.w3.org/TR/xpath-functions/#func-month-from-dateTime).
+    #
+    # @return [Integer]
+    # @see https://www.w3.org/TR/xpath-functions/#func-month-from-dateTime
+    def month; Integer.new(object.month); end
+
+    # Days
+    #
+    # From the XQuery function [fn:day-from-dateTime](https://www.w3.org/TR/xpath-functions/#func-day-from-dateTime).
+    #
+    # @return [Integer]
+    # @see https://www.w3.org/TR/xpath-functions/#func-day-from-dateTime
+    def day; Integer.new(object.day); end
+
+    # Hours
+    #
+    # From the XQuery function [fn:hours-from-dateTime](https://www.w3.org/TR/xpath-functions/#func-hours-from-dateTime).
+    #
+    # @return [Integer]
+    # @see https://www.w3.org/TR/xpath-functions/#func-hours-from-dateTime
+    def hours; Integer.new(object.hour); end
+
+    # Minutes
+    #
+    # From the XQuery function [fn:minutes-from-dateTime](https://www.w3.org/TR/xpath-functions/#func-minutes-from-dateTime).
+    #
+    # @return [Integer]
+    # @see https://www.w3.org/TR/xpath-functions/#func-minutes-from-dateTime
+    def minutes; Integer.new(object.min); end
+
+    # Seconds
+    #
+    # From the XQuery function [fn:seconds-from-dateTime](https://www.w3.org/TR/xpath-functions/#func-seconds-from-dateTime).
+    #
+    # @return [Decimal]
+    # @see https://www.w3.org/TR/xpath-functions/#func-seconds-from-dateTime
+    def seconds; Decimal.new(object.strftime("%S.%L")); end
+  end # Temporal
+end; end # RDF::Literal