001/*
002 * Shredzone Commons - suncalc
003 *
004 * Copyright (C) 2017 Richard "Shred" Körber
005 *   http://commons.shredzone.org
006 *
007 * Licensed under the Apache License, Version 2.0 (the "License");
008 * you may not use this file except in compliance with the License.
009 *
010 * This program is distributed in the hope that it will be useful,
011 * but WITHOUT ANY WARRANTY; without even the implied warranty of
012 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
013 */
014package org.shredzone.commons.suncalc.param;
015
016/**
017 * Location based parameters.
018 * <p>
019 * Use them to give information about the geolocation of the observer. If ommitted, a
020 * latitude and longitude of 0° is used.
021 *
022 * @param <T>
023 *            Type of the final builder
024 */
025public interface LocationParameter<T> {
026
027    /**
028     * Sets the geolocation.
029     *
030     * @param lat
031     *            Latitude, in degrees.
032     * @param lng
033     *            Longitude, in degrees.
034     * @return itself
035     */
036    T at(double lat, double lng);
037
038    /**
039     * Sets the geolocation. In the given array, index 0 must contain the latitude, and
040     * index 1 must contain the longitude. An optional index 2 may contain the height, in
041     * meters.
042     * <p>
043     * This call is meant to be used for coordinates stored in constants.
044     *
045     * @param coords
046     *            Array containing the latitude and longitude, in degrees.
047     * @return itself
048     */
049    T at(double[] coords);
050
051    /**
052     * Sets the latitude.
053     *
054     * @param lat
055     *            Latitude, in degrees.
056     * @return itself
057     */
058    T latitude(double lat);
059
060    /**
061     * Sets the longitude.
062     *
063     * @param lng
064     *            Longitude, in degrees.
065     * @return itself
066     */
067    T longitude(double lng);
068
069    /**
070     * Sets the latitude.
071     *
072     * @param d
073     *            Degrees
074     * @param m
075     *            Minutes
076     * @param s
077     *            Seconds (and fraction of seconds)
078     * @return itself
079     */
080    T latitude(int d, int m, double s);
081
082    /**
083     * Sets the longitude.
084     *
085     * @param d
086     *            Degrees
087     * @param m
088     *            Minutes
089     * @param s
090     *            Seconds (and fraction of seconds)
091     * @return itself
092     */
093    T longitude(int d, int m, double s);
094
095    /**
096     * Sets the height.
097     *
098     * @param h
099     *            Height, in meters above sea level. Default: 0.0 m. Negative values are
100     *            silently changed to the acceptable minimum of 0.0 m.
101     * @return itself
102     */
103    T height(double h);
104
105    /**
106     * Uses the same location as given in the {@link LocationParameter} at this moment.
107     * <p>
108     * Changes to the source parameter will not affect this parameter, though.
109     *
110     * @param l  {@link LocationParameter} to be used.
111     * @return itself
112     * @since 2.8
113     */
114    T sameLocationAs(LocationParameter<?> l);
115
116}