Can you clarify which library and version? And do you already have code (its much easier to
give concrete examples relating to existing code)
Conceptually the DS1307 looks like a 64 byte non-volatile RAM with special behaviour of the
first 8 addresses. The I2C interface allows specifying a starting address and then writing or reading
consecutive bytes from that point.
Neat functions. What is the purpose of the isrunning function? Must the RTC clock be stopped to write (or read) into the scratch pad ram locations?
Just quick-and-dirty stuff really, but it gets the job done. I don't think it's an absolute requirement, but yes the usual practice is to stop the RTC while setting the time to avoid any unwanted rollover in the time registers. OTOH, just setting the seconds register first would seem to be safe enough in most cases as this also resets the divider chain.
But in this case I was relying on a library to set the RTC. I use the Time library a lot, and because it syncs with a hardware RTC every 5 minutes (by default), an interesting thing happens. When initially powered up, the RTC's clock is halted. Still, the Time library can read the time from it (usually 1/1/2000 00:00) and then the time as returned by the Time library will advance as normal for the next five minutes. When it syncs with the hardware RTC again, the time snaps back to 1/1/2000 00:00.
I had a sketch where I wanted to ensure the RTC was running so as to avoid this, even if the RTC time was wrong. So in setup() I do
if (!dsIsRunning()) RTC.set(RTC.get());
which basically leaves the RTC time set to the same value as before, but ensures its clock is running. (The library function RTC.set() stops the RTC clock, sets the time, then starts the clock again.)