KosherSwift Zmanim API

这个 Zmanim 库是一个针对特定日历的 API，可以计算不同的天文时间，包括日出和日落，以及犹太 zmanim（宗教时间）用于祈祷和其他犹太宗教职责。

对于非宗教的天文/太阳计算，请使用 AstronomicalCalendar。

ZmanimCalendar 包含最常见的 zmanim 或宗教时间计算。对于更详细的 zmanim 列表，请使用 ComplexZmanimCalendar。此类包含 Zmanim 库的主要功能。

有关 API 的基本使用说明，请参阅如何使用 Zmanim API，zmanim 代码示例和 KosherJava 常见问题解答。有关更多信息，请访问 KosherJava Zmanim 网站。

入门

将 KosherSwift 添加为您的项目依赖项

复制此行

https://github.com/Elyahu41/KosherSwift.git

进入 Xcode 中的包依赖项并搜索此仓库并添加它！

如何使用此API

在添加此项目后，您可以前往任何文件/视图控制器并导入框架

import KosherSwift

然后，只需实例化一个类并调用它的方法即可

let jewishCalendar = JewishCalendar() // by default it is set to today's date
print(jewishCalendar.getJewishMonth()) // This will print the jewish month as a number, so Nissan will be 8. See the JewishCalendr class for more details

对于日出和日落时间，您需要一个GeoLocation对象。然后，您需要将此传递给AstronomicalCalendar类，如下所示

let geoLocation = GeoLocation(locationName: "Lakewood, NJ", latitude: 40.08213, longitude: -74.20970, timeZone: TimeZone(identifier: "America/New_York")!)
// The locationName string can be left empty if you'd like. There is also a constructor for elevation to be added.
// There are two Sunrise/Sunset calculators in this API, the NOAA Calculator and the SunTimes Calculator. By default, the NOAA calculator is used as it is more accurate than the SunTimes calculator as it takes into account leap years and other things.
let cal = AstronomicalCalendar(location: geoLocation)
// To use the SunTimesCalculator:
// cal.astronomicalCalculator = SunTimesCalculator()
let sunrise = cal.getSunrise() // This will return a nullable Date? object

对于zmanim，您将做同样的事情，只需使用ComplexZmanimCalendar或ZmanimCalendar类

let geoLocation = GeoLocation(locationName: "Lakewood, NJ", latitude: 40.08213, longitude: -74.20970, timeZone: TimeZone(identifier: "America/New_York")!)
let cal = ComplexZmanimCalendar(location: geoLocation)
let sunrise = cal.getSofZmanShmaGRA() // This will return a nullable Date? object

如果您想计算某个日期的zman

var gregorianCalendar = Calendar(identifier: .gregorian)
gregorianCalendar.timeZone = TimeZone(identifier: "America/New_York")! // It is important to set the Timezone as the date can change in Swift
        
let geoLocation = GeoLocation(locationName: "", latitude: 40.08213, longitude: -74.20970, timeZone: TimeZone(identifier: "America/New_York")!)
let calendar = ComplexZmanimCalendar(geoLocation: geoLocation) // Timezone is kept track of inside these classes with the geolocation

var januaryFirst = DateComponents()
januaryFirst.year = 2023
januaryFirst.month = 1
januaryFirst.day = 1
        
calendar.workingDate = gregorianCalendar.date(from: januaryFirst)!
var sunrise = calendar.getSunrise()

要将此API中的任何数据转换为希伯来文，请查看HebrewDateFormatter类

let jewishCalendar = JewishCalendar() // by default it is set to today's date
let hebrewDateFormatter = HebrewDateFormatter()
print(hebrewDateFormatter.formatMonth(jewishCalendar: jewishCalendar)) // prints "Nissan"
hebrewDateFormatter.hebrewFormat = true
print(hebrewDateFormatter.formatMonth(jewishCalendar: jewishCalendar)) // prints "ניסן"

最后，查看TefilaRules类以获取使用犹太日历告诉您要祈祷的方法

let jewishCalendar = JewishCalendar()
let tefilaRules = TefilaRules()
tefilaRules.isVeseinTalUmatarRecited(jewishCalendar: jewishCalendar) // returns true or false depending on the DAY of the year

自定义方法

如果您想增加KosherSwift中已有的功能，Swift有一个强大特性叫做扩展（extensions），可以让您这样做！例如，如果您想创建一个方法来获得设置为犹太月第一天的jewishCalendar对象，您可以这样操作

public extension JewishCalendar {
    func getFirstDayOfJewishMonth(jewishCalendar:JewishCalendar) -> JewishCalendar {
        let firstDayOfMonth = jewishCalendar
        jewishCalendar.setJewishDayOfMonth(dayOfMonth: 1)
        return firstDayOfMonth
    }
}

对于zmanim也是如此！如果您想创建自己的zmanim，它会看起来像这样

public extension ComplexZmanimCalendar {
    
    // for degrees
    func getTzais8PointSevenDegrees() -> Date? {
        return getSunsetOffsetByDegrees(offsetZenith: ComplexZmanimCalendar.GEOMETRIC_ZENITH + 8.7);
    }
    
    // for seasonal times
    func getTwoSeasonalHoursIntoTheDay() -> Date? {
        let seasonalHour = getTemporalHour()
        // it is preffered to use getTimeOffset because it will handle nil values
        return AstronomicalCalendar.getTimeOffset(time: getSeaLevelSunrise(), offset: seasonalHour * 2)
    }
}

注意事项

KosherSwift与KosherJava非常相似，因为它几乎将其所有方法都带到Swift中。然而，类内的工作方式也存在重大差异。首先，Swift中的Calendar类不包含以毫秒为单位的时间来跟踪时间，它只包含可以创建日期的函数。因此，在需要使用Calendar的地方已被Date替换。如果您查看类的代码，您会看到一个可更改的workingDate变量，而不是Calendar类。

时区问题在 Swift 中非常重要，因为日期对象默认设置为 UTC，并且仅在之后才会考虑时区，这会导致日期变化，如果 Swift 中 Calendar 类的时区没有设置为与系统时区相同。所有具有 GeoLocation 对象的对象都会考虑这一点，但如果您在使用 JewishCalendar 类的其他时区，请使用 JewishCalendar(workingDate: , timezone:) 构造函数。

否则，大多数方法都经过尝试和测试，但是，如果您遇到一个不正常工作的方法，请创建问题或（更理想的是）拉取请求。